# XXTouch 中文完整文档上下文

> XXTouch 中文文档的完整 Markdown 上下文，由构建脚本从源文档生成。

本文件由站点构建脚本从源 Markdown 文档生成。

文档数量: 633

---

Source: [关于 XXTouch](https://xxtouch.app/docs/index.md)
Path: README.md

# 关于 XXTouch

XXTouch 以 Lua 作为脚本语言，全面支持 Lua 5.3 的语法与标准库，并在此基础上扩展了取色、找色、模拟触摸与键盘事件等高级功能。脚本文件必须使用 UTF-8 编码。

---

- [开发及周边工具下载](/docs/handbook/supplement/dev-tools.md)
- [开发手册](/docs/handbook/index.md)
- [OpenAPI](/docs/OpenAPI/index.md)
- [XPP 脚本包](/docs/XPP/index.md)
- [XUI 界面库](/docs/XUI/index.md)
- [URL Scheme 与二维码协议](/docs/URLScheme/index.md)
- [常见问题答疑](/docs/FAQ/index.md)

---

Source: [开发手册目录](https://xxtouch.app/docs/handbook/index.md)
Path: handbook/README.md

# 开发手册目录

## 如何阅读本手册

- 入门需要 Lua 基础，可参考[《Lua 5.3 教程》](https://www.runoob.com/lua/lua-basic-syntax.html)及[《Lua 5.3 函数参考》](https://www.zybuluo.com/havonz/note/564563)
- 示例代码中以 `0x` 开头的数字为十六进制数（[Wikipedia - 十六进制](https://zh.wikipedia.org/wiki/%E5%8D%81%E5%85%AD%E8%BF%9B%E5%88%B6)）
- 参数描述中，可选参数以中括号包围
- 若参数或返回值为表型固定结构，则使用大括号表示其结构
- 类型描述中"文本型"和"字符串型"都对应 Lua 的 string 类型，但"文本型"通常指可打印的明文文字
- 章节标题以叹号（!）开头的，表示该函数或模块包含隐式**让出**（在函数返回之前，其他[线程](thread/README.md)可能获得执行机会）
- 除非另有说明，手册中的示例代码均不处理边界情况，不宜直接复制到生产脚本中使用


---

- [开发工具下载](supplement/dev-tools.md)
- [如何使用 XXTouch](how-to-use/README.md)
- [保护脚本，正确接受 require](secure-require/README.md)
- [全局变量](globals/README.md)
- [基本控制函数](control-flow/README.md)
- [开发辅助函数](develop-helper/README.md)
- [屏幕模块 (screen)](screen/README.md)
- [模拟触摸模块 (touch)](touch/README.md)
- [模拟按键模块 (key)](key/README.md)
- [硬件鼠标模块 (mouse)](mouse/README.md)
- [硬件游戏手柄模块 (gamepad)](gamepad/README.md)
- [文本元素模块 (ui_element)](ui_element/README.md)
- [系统模块 (sys)](sys/README.md)
- [剪贴板模块 (pasteboard)](pasteboard/README.md)
- [对话框模块 (dialog)](dialog/README.md)
- [清理模块 (clear)](clear/README.md)
- [应用程序模块 (app)](app/README.md)
- [设备相关模块 (device)](device/README.md)
- [图片对象模块 (image)](image/README.md)
- [CoreML 模块 (coreml)](coreml/README.md)
- [ONNX Runtime 模块 (onnxruntime)](onnxruntime/README.md)
- [进程字典相关函数](proc/README.md)
- [线程模块 (thread)](thread/README.md)
- [Web 视图模块 (webview)](webview/README.md)
- [XPP 脚本包模块 (xpp)](xpp/README.md)
- [XUI 脚本配置界面模块 (xui)](xui/README.md)
- [扩展 table 模块 (table)](ext-table/README.md)
- [扩展 string 模块 (string)](ext-string/README.md)
- [! HTTP 模块 (http)](http/README.md)
- [! FTP 模块 (ftp)](ftp/README.md)
- [JSON 模块 (json)](json/README.md)
- [PLIST 读写模块 (plist)](plist/README.md)
- [小工具模块 (utils)](utils/README.md)
- [文件操作模块 (file)](file/README.md)
- [VPN 配置模块 (vpnconf)](vpnconf/README.md)
- [系统回调消息](system-callback/README.md)
- [已集成的开源扩展库](open-source/README.md)
- [附录](supplement/README.md)

---

Source: [如何使用 XXTouch](https://xxtouch.app/docs/handbook/how-to-use/index.md)
Path: handbook/how-to-use/README.md

# 如何使用 XXTouch

---

## 脚本及相关资源的存储位置

| 用途 | 路径变量 | 有根版路径参考 |
| --- | --- | --- |
| 资源目录 | [`XXT_RES_PATH`](../globals/README.md#xxt_res_path) | `/var/mobile/Media/1ferver/res/` |
| 脚本目录 | [`XXT_SCRIPTS_PATH`](../globals/README.md#xxt_scripts_path) | `/var/mobile/Media/1ferver/lua/scripts/` |
| 内置脚本模块目录 | [`XXT_LUA_PATH`](../globals/README.md#xxt_lua_path) | `/var/mobile/Media/1ferver/lua/` |
| 插件目录 | [`XXT_LIB_PATH`](../globals/README.md#xxt_lib_path) | `/var/mobile/Media/1ferver/lib/` |
| 日志目录 | [`XXT_LOG_PATH`](../globals/README.md#xxt_log_path) | `/var/mobile/Media/1ferver/log/` |
| 推理模型目录 | [`XXT_MODELS_PATH`](../globals/README.md#xxt_models_path) | `/var/mobile/Media/1ferver/models/` |
| 旧文字识别字库目录 | [`XXT_TESSDATA_PATH`](../globals/README.md#xxt_tessdata_path) | `/var/mobile/Media/1ferver/tessdata/` |

上述路径变量的值由运行时根据安装版本动态生成。

## 售前及安装答疑

- [前往查看](/docs/FAQ/index.md)

## 用户使用图文说明

- [前往查看](/docs/ABC.md)

## 开发相关及交流群

- [开发及周边工具下载](/docs/handbook/supplement/dev-tools.md)
- [XXTouch 技术交流群](https://t.me/xxtouch_chat)

---

Source: [保护脚本，正确接受 require](https://xxtouch.app/docs/handbook/secure-require/index.md)
Path: handbook/secure-require/README.md

# 保护脚本，正确接受 require

---

## 为何 require 可能带来安全风险？

- XXTouch 加密的脚本模块可被其它脚本或模块以 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 方式引用
- 当加密脚本被 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 时，全局环境是不可信的，脚本调用的函数可能已被替换


## 如何正确使用 require 呢？

- XXTouch 保证部分模块的函数会在被 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 之前恢复初始状态，包括 `os`、`io`、`string`、`device`、`http`、`file`、`table` 模块的所有函数
- 可通过深拷贝全局环境到模块内局部环境来确保安全调用上述模块中的函数，例如：
  ```lua
  -- 在脚本的最前面加上这个代码
  local _ENV = table.deep_copy(_ENV)
  -- 下面就是脚本的主体内容
  --
  -- 最后您可能还需要返回一些导出函数或者常量
  ```
- 当一个模块被 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 方式引用时，全局变量 `been_require` 会无条件置为 `true`，可通过该变量判断当前脚本是否正在被 require，例如：
  ```lua
  -- 在脚本的最前面加上这个代码
  if been_require then
      return -- 如果被 require 就直接退出
  end
  -- 下面就是脚本的主体内容
  ```

---

Source: [全局变量](https://xxtouch.app/docs/handbook/globals/index.md)
Path: handbook/globals/README.md

# 全局变量

Lua 中没有常量的概念，因此使用一些全局变量来表示常量。

以下路径变量的值在运行时根据安装版本动态生成，通常无需关心具体路径；在无根 (rootless) 或巨魔 (TrollStore) 版中可能位于其他挂载点，如需手动拼接系统根下的路径，请参考 [`jbroot`](/docs/handbook/develop-helper/jbroot.md)。

---

## 路径

### XXT_HOME_PATH

XXT 主目录
有根版中为 `/var/mobile/Media/1ferver/`

### XXT_RES_PATH {#xxt_res_path}

XXT 资源目录
有根版中为 `/var/mobile/Media/1ferver/res/`

### XXT_SCRIPTS_PATH {#xxt_scripts_path}

XXT 脚本目录
有根版中为 `/var/mobile/Media/1ferver/lua/scripts/`

### XXT_LUA_PATH {#xxt_lua_path}

XXT Lua 扩展库目录
有根版中为 `/var/mobile/Media/1ferver/lua/`

### XXT_LIB_PATH {#xxt_lib_path}

XXT C 扩展库目录
有根版中为 `/var/mobile/Media/1ferver/lib/`

### XXT_LOG_PATH {#xxt_log_path}

XXT 日志目录
有根版中为 `/var/mobile/Media/1ferver/log/`

### XXT_MODELS_PATH {#xxt_models_path}

XXT 推理模型目录
有根版中为 `/var/mobile/Media/1ferver/models/`

### XXT_TESSDATA_PATH（已弃用） {#xxt_tessdata_path}

XXT 旧文字识别字库目录
有根版中为 `/var/mobile/Media/1ferver/tessdata/`

## 状态

### IS_TROLLSTORE_EDITION

当前是否为 TrollStore 版本

---

Source: [基本控制函数](https://xxtouch.app/docs/handbook/control-flow/index.md)
Path: handbook/control-flow/README.md

# 基本控制函数

---

- [结束脚本 (os.exit)](os.exit.md)
- [重启脚本 (os.restart)](os.restart.md)
- [注册终止回调 (register_atexit)](register_atexit.md)
- [脚本被终止时执行一些代码的方法](terminate-callback.md)

---

Source: [开发辅助函数](https://xxtouch.app/docs/handbook/develop-helper/index.md)
Path: handbook/develop-helper/README.md

# 开发辅助函数

---

- [打印内容到缓冲区 (print)](print.md)
- [将打印缓冲区的内容提出来 (print.out)](print.out.md)
- [网络日志 (nLog)](nLog.md)
- [获取系统根路径对应的越狱根路径 (jbroot)](jbroot.md)
- [获取越狱根对应的系统根路径 (rootfs)](rootfs.md)
- [获取当前脚本已执行毫秒数 (get_elapsed_ms)](get_elapsed_ms.md)

---

Source: [屏幕模块 (screen)](https://xxtouch.app/docs/handbook/screen/index.md)
Path: handbook/screen/README.md

# 屏幕模块 (screen)

---

- [初始化旋转坐标系 (screen.init)](screen.init.md)
- [获取屏幕尺寸 (screen.size)](screen.size.md)
- [获取屏幕缩放因子 (screen.scale_factor)](screen.scale_factor.md)
- [保持屏幕 (screen.keep)](screen.keep.md)
- [取消保持屏幕 (screen.unkeep)](screen.unkeep.md)
- [获取屏幕上某点颜色 (screen.get_color)](screen.get_color.md)
- [获取屏幕上某点颜色 RGB (screen.get_color_rgb)](screen.get_color_rgb.md)
- [屏幕多点颜色匹配 (screen.is_colors)](screen.is_colors.md)
- [多点相似度模式找色 (screen.find_color)](screen.find_color-cs.md)
- [多点色偏模式找色 (screen.find_color)](screen.find_color-co.md)
- [获取屏幕图像 (screen.image)](screen.image.md)
- [! 屏幕区域文字识别 (screen.ocr_text)](screen.ocr_text.md)
- [屏幕找图 (screen.find_image)](screen.find_image.md)
- [坐标旋转转换 (screen.rotate_xy)](screen.rotate_xy.md)
- [反向坐标旋转转换 (screen.unrotate_xy)](screen.unrotate_xy.md)

---

Source: [模拟触摸模块 (touch)](https://xxtouch.app/docs/handbook/touch/index.md)
Path: handbook/touch/README.md

# 模拟触摸模块 (touch)

---

- [! 模拟手指轻触一次屏幕 (touch.tap)](touch.tap.md)
- [模拟手指接触屏幕 (touch.on)](touch.on.md)
- [! 模拟手指在屏幕上移动 (:move)](touchm_move.md)
- [! 模拟手指在屏幕上施加压力 (:press)](touchm_press.md)
- [模拟手指离开屏幕 (:off)](touchm_off.md)
- [设置触摸事件对象移动步长 (:step_len)](touchm_step_len.md)
- [设置触摸事件对象移动每步延迟 (:step_delay)](touchm_step_delay.md)
- [! 毫秒级延迟 (:msleep)](touchm_msleep.md)
- [touch 示例代码](samples-1.md)

---

Source: [模拟按键模块 (key)](https://xxtouch.app/docs/handbook/key/index.md)
Path: handbook/key/README.md

# 模拟按键模块 (key)

---

- [! 模拟按一下物理按键 (key.press)](key.press.md)
- [模拟按下物理按键 (key.down)](key.down.md)
- [松开按下的物理按键 (key.up)](key.up.md)
- [! 模拟键入文本 (key.send_text)](key.send_text.md)
- [输入文字 (key.input_text)](key.input_text.md)
- [示例及支持的键码列表](samples.md)

> **以下硬件键盘相关函数和方法在 20260805 以后版本方可使用**

- [! 创建独立硬件键盘对象 (key.connect_keyboard)](key.connect_keyboard.md)
- [! 连接全局硬件键盘 (key.connect_global_keyboard)](key.connect_global_keyboard.md)
- [获取当前全局硬件键盘 (key.get_global_keyboard)](key.get_global_keyboard.md)
- [断开全局硬件键盘 (key.disconnect_global_keyboard)](key.disconnect_global_keyboard.md)
- [按下硬件键盘按键 (:down)](hardware_keyboardm_down.md)
- [松开硬件键盘按键 (:up)](hardware_keyboardm_up.md)
- [! 按一下硬件键盘按键 (:press)](hardware_keyboardm_press.md)
- [! 使用硬件键盘输入文本 (:send_text)](hardware_keyboardm_send_text.md)
- [判断硬件键盘是否已连接 (:is_connected)](hardware_keyboardm_is_connected.md)
- [获取硬件键盘配置属性 (:get_properties)](hardware_keyboardm_get_properties.md)
- [断开硬件键盘 (:disconnect)](hardware_keyboardm_disconnect.md)

---

Source: [硬件鼠标模块 (mouse)](https://xxtouch.app/docs/handbook/mouse/index.md)
Path: handbook/mouse/README.md

# 硬件鼠标模块 (mouse)

> **该模块在 20260805 以后版本方可使用**

`mouse` 模块用于创建独立的硬件鼠标对象。每次调用 `mouse.connect` 都会创建一个新的鼠标对象，各对象的按键状态和生命周期互不影响。

---

- [! 创建并连接一个硬件鼠标对象 (mouse.connect)](mouse.connect.md)
- [移动硬件鼠标 (:move)](mousem_move.md)
- [按下硬件鼠标按键 (:down)](mousem_down.md)
- [松开硬件鼠标按键 (:up)](mousem_up.md)
- [! 点击硬件鼠标按键 (:click)](mousem_click.md)
- [滚动硬件鼠标滚轮 (:scroll)](mousem_scroll.md)
- [获取硬件鼠标连接状态 (:is_connected)](mousem_is_connected.md)
- [获取硬件鼠标创建属性 (:get_properties)](mousem_get_properties.md)
- [断开硬件鼠标 (:disconnect)](mousem_disconnect.md)

---

Source: [硬件游戏手柄模块 (gamepad)](https://xxtouch.app/docs/handbook/gamepad/index.md)
Path: handbook/gamepad/README.md

# 硬件游戏手柄模块 (gamepad)

> **该模块在 20260805 以后版本方可使用**

`gamepad` 模块用于创建独立的游戏手柄对象。每次调用 `gamepad.connect` 都会创建一个新的手柄对象，各对象的按键、摇杆、方向键状态和生命周期互不影响。

---

- [! 创建硬件游戏手柄 (gamepad.connect)](gamepad.connect.md)
- [按下手柄按键 (:down)](gamepadm_down.md)
- [松开手柄按键 (:up)](gamepadm_up.md)
- [! 按一下手柄按键 (:press)](gamepadm_press.md)
- [设置手柄摇杆位置 (:set_stick)](gamepadm_set_stick.md)
- [设置手柄方向键状态 (:set_dpad)](gamepadm_set_dpad.md)
- [复位手柄状态 (:reset)](gamepadm_reset.md)
- [判断手柄是否已连接 (:is_connected)](gamepadm_is_connected.md)
- [获取手柄设备属性 (:get_properties)](gamepadm_get_properties.md)
- [断开硬件游戏手柄 (:disconnect)](gamepadm_disconnect.md)

---

Source: [文本元素模块 (ui_element)](https://xxtouch.app/docs/handbook/ui_element/index.md)
Path: handbook/ui_element/README.md

# 文本元素模块 (ui_element)

> **该模块在 20260507 以后版本方可使用**

`ui_element` 用于按文本、角色、状态或坐标读取当前界面上的 UI 元素，并对匹配到的元素执行点击、滚动、输入、切换、调节等操作。它适合脚本需要理解界面结构、减少硬编码坐标、或在不同分辨率设备上保持可读定位逻辑的场景。

固定坐标触控仍建议使用 [模拟触摸模块 (touch)](/docs/handbook/touch/index.md)。`ui_element` 中出现的坐标均为物理像素。

## 基本用法

```lua
local ui_element = require("ui_element")

local item, err = ui_element.find({
    title = "搜索",
    role = "text_field",
})

if item then
    ui_element.input_text(item, "hello")
else
    sys.toast(err)
end
```

## 说明

> 查询类接口失败时通常返回 `nil, err`。
> `find_all` 没有匹配项时返回空数组。
> 动作类接口成功时返回 `true, info`，失败时返回 `nil, err`。
> 界面发生变化后，之前获取到的快照不再代表最新界面，应重新调用 `snapshot()`。

---

- [选择器字段说明](selector.md)
- [元素字段说明](element.md)
- [通用选项说明](options.md)
- [ui_element 使用示例](samples.md)
- [获取文本元素列表 (ui_element.list_text_elements)](ui_element.list_text_elements.md)
- [获取坐标处的 UI 元素 (ui_element.text_element_at_position)](ui_element.text_element_at_position.md)
- [查找一个 UI 元素 (ui_element.find)](ui_element.find.md)
- [查找多个 UI 元素 (ui_element.find_all)](ui_element.find_all.md)
- [获取一次 UI 快照 (ui_element.snapshot)](ui_element.snapshot.md)
- [点击 UI 元素 (ui_element.click)](ui_element.click.md)
- [滚动 UI 元素或当前页面 (ui_element.scroll)](ui_element.scroll.md)
- [追加输入文本 (ui_element.input_text)](ui_element.input_text.md)
- [设置文本内容 (ui_element.set_text)](ui_element.set_text.md)
- [清空文本内容 (ui_element.clear_text)](ui_element.clear_text.md)
- [切换控件状态 (ui_element.toggle)](ui_element.toggle.md)
- [设置勾选状态 (ui_element.set_checked)](ui_element.set_checked.md)
- [设置控件值 (ui_element.set_value)](ui_element.set_value.md)
- [增加控件值 (ui_element.increase)](ui_element.increase.md)
- [减少控件值 (ui_element.decrease)](ui_element.decrease.md)

---

Source: [系统模块 (sys)](https://xxtouch.app/docs/handbook/sys/index.md)
Path: handbook/sys/README.md

# 系统模块 (sys)

---

- [显示提示文字 (sys.toast)](sys.toast.md)
- [弹出系统提示 (sys.alert)](sys.alert.md)
- [弹出输入提示 (sys.input_box)](sys.input_box.md)
- [输入文字 (sys.input_text)](sys.input_text.md)
- [! 毫秒级延迟 (sys.msleep)](sys.msleep.md)
- [获取当前毫秒级时间戳 (sys.mtime)](sys.mtime.md)
- [! 获取网络时间 (sys.net_time)](sys.net_time.md)
- [产生一个随机数 (sys.rnd)](sys.rnd.md)
- [获取设备当前内存状态信息 (sys.memory_info)](sys.memory_info.md)
- [获取设备当前可用内存值 (sys.available_memory)](sys.available_memory.md)
- [获取设备当前未使用的存储空间值 (sys.free_disk_space)](sys.free_disk_space.md)
- [输出标准系统日志 (sys.log)](sys.log.md)
- [给指定进程号的进程发送信号 (sys.kill)](sys.kill.md)
- [发送信号给指定名称的进程 (sys.killall)](sys.killall.md)
- [递归修改文件所有者 (sys.lchown_r)](sys.lchown_r.md)
- [递归修改文件权限 (sys.lchmod_r)](sys.lchmod_r.md)
- [递归修改文件所有者与权限 (sys.lchownmod_r)](sys.lchownmod_r.md)
- [递归创建目录 (sys.mkdir_p)](sys.mkdir_p.md)
- [创建一个执行任务 (sys.task)](sys.task.md)
- [问系统一个问题 (sys.mgcopyanswer)](sys.mgcopyanswer.md)
- [读取 sysctl 键值 (sys.ctlbyname)](sys.ctlbyname.md)
- [获取系统版本 (sys.version)](sys.version.md)
- [获取 CoreFoundation 版本 (sys.cfversion)](sys.cfversion.md)
- [获取 XXTouch 版本 (sys.xtversion)](sys.xtversion.md)
- [读取或设置允许 App 请求跟踪 (sys.user_tracking / sys.set_user_tracking)](sys.user_tracking.md)
- [读取或设置个性化广告 (sys.personalized_advertising / sys.set_personalized_advertising)](sys.personalized_advertising.md)
- [读取或设置定位服务 (sys.location_services / sys.set_location_services)](sys.location_services.md)

---

Source: [剪贴板模块 (pasteboard)](https://xxtouch.app/docs/handbook/pasteboard/index.md)
Path: handbook/pasteboard/README.md

# 剪贴板模块 (pasteboard)

---

- [写内容进剪贴板 (pasteboard.write)](pasteboard.write.md)
- [写剪贴板项目 (pasteboard.write_items)](pasteboard.write_items.md)
- [获取剪贴板中的数据 (pasteboard.read)](pasteboard.read.md)
- [清空剪贴板 (pasteboard.clear)](pasteboard.clear.md)

---

Source: [对话框模块 (dialog)](https://xxtouch.app/docs/handbook/dialog/index.md)
Path: handbook/dialog/README.md

# 对话框模块 (dialog)

dialog 界面默认使用 webview 引擎实现。在巨魔版或 iOS 16 及以上系统中，默认使用 XUI 引擎。

可通过以下方式强制指定引擎：
- `dialog.engine = "webview"` — 强制使用 webview 引擎
- `dialog.engine = "xui"` — 强制使用 XUI 引擎

---

- [! 建立一个对话框对象 (dialog)](new.md)
- [配置对话框配置保存文件名 (:set_config)](dialogm_set_config.md)
- [配置对话框自动消失时间 (:set_timeout)](dialogm_set_timeout.md)
- [配置对话框的标题 (:set_title)](dialogm_set_title.md)
- [配置对话框的尺寸 (:set_size)](dialogm_set_size.md)
- [配置对话框的位置及尺寸 (:set_frame)](dialogm_set_frame.md)
- [配置对话框的圆角半径 (:set_corner_radius)](dialogm_set_corner_radius.md)
- [给对话框加上一个文本标签 (:add_label)](dialogm_add_label.md)
- [给对话框加上一个文本输入框 (:add_input)](dialogm_add_input.md)
- [给对话框加上一个图片 (:add_image)](dialogm_add_image.md)
- [给对话框加上一个开关 (:add_switch)](dialogm_add_switch.md)
- [给对话框加上一个选择器 (:add_picker)](dialogm_add_picker.md)
- [给对话框加上一个单选组 (:add_radio)](dialogm_add_radio.md)
- [给对话框加上一个多选组 (:add_checkbox)](dialogm_add_checkbox.md)
- [给对话框加上一个数值选择器 (:add_range)](dialogm_add_range.md)
- [! 将对话框弹出来并返回用户的选择 (:show)](dialogm_show.md)
- [! 在不弹出对话框的情况下获得对话框配置 (:load)](dialogm_load.md)

---

Source: [清理模块 (clear)](https://xxtouch.app/docs/handbook/clear/index.md)
Path: handbook/clear/README.md

# 清理模块 (clear)

---

- [清理某个或某组钥匙串信息 (clear.keychain)](clear.keychain.md)
- [清理所有应用程序钥匙串信息 (clear.all_keychain)](clear.all_keychain.md)
- [清理浏览器 Cookies (clear.cookies)](clear.cookies.md)
- [清理系统缓存 (clear.caches)](clear.caches.md)
- [清除相册中所有本地照片 (clear.all_photos)](clear.all_photos.md)
- [清理某个应用的存档数据 (clear.app_data)](clear.app_data.md)
- [清理 IDFA/V (clear.idfav)](clear.idfav.md)

---

Source: [应用程序模块 (app)](https://xxtouch.app/docs/handbook/app/index.md)
Path: handbook/app/README.md

# 应用程序模块 (app)

本模块围绕两个核心标识来操作应用：

- **bundle identifier（应用包标识符，bid）**：应用的唯一字符串标识，如 `com.tencent.mqq`；安装后不变。可在 **XXT 应用程序 → 更多 → 应用列表** 中查看。
- **process identifier（进程标识符，pid）**：应用运行时的进程号，整数，每次启动都不同。

---

- [获取 App 的应用程序包路径 (app.bundle_path)](app.bundle_path.md)
- [获取 App 的应用存档路径 (app.data_path)](app.data_path.md)
- [获取 App 的应用分组信息 (app.group_info)](app.group_info.md)
- [获取 App 的插件信息 (app.plugin_info)](app.plugin_info.md)
- [弹出一个应用通知 (app.pop_banner)](app.pop_banner.md)
- [运行应用程序 (app.run)](app.run.md)
- [关闭应用程序 (app.close)](app.close.md)
- [模拟使用上划退出应用程序 (app.quit)](app.quit.md)
- [检测应用程序是否正在运行 (app.is_running)](app.is_running.md)
- [通过应用程序 bid 获取应用的本地化名字 (app.localized_name)](app.localized_name.md)
- [通过应用程序 bid 获取应用的图标数据 (app.png_data_for_bid)](app.png_data_for_bid.md)
- [通过应用程序 bid 获取其 pid (app.pid_for_bid)](app.pid_for_bid.md)
- [获取应用程序当前内存消耗 (app.used_memory)](app.used_memory.md)
- [获取前台应用的包标识符 (app.front_bid)](app.front_bid.md)
- [获取前台应用的进程号 (app.front_pid)](app.front_pid.md)
- [前台打开一个 URL (app.open_url)](app.open_url.md)
- [获取设备所有的应用的包标识符列表 (app.bundles)](app.bundles.md)
- [获取当前设备的进程列表 (app.all_procs)](app.all_procs.md)
- [设置 App 的 TCC 权限 (app.set_tcc)](app.set_tcc.md)
- [获取 App 打开的文件 (app.lsof)](app.lsof.md)
- [! 安装 IPA 安装包 (app.install)](app.install.md)
- [卸载一个应用 (app.uninstall)](app.uninstall.md)

---

Source: [设备相关模块 (device)](https://xxtouch.app/docs/handbook/device/index.md)
Path: handbook/device/README.md

# 设备相关模块 (device)

---

- [重置自动锁屏倒计时 (device.reset_idle)](device.reset_idle.md)
- [锁定屏幕 (device.lock_screen)](device.lock_screen.md)
- [解锁屏幕 (device.unlock_screen)](device.unlock_screen.md)
- [获取屏幕锁定状态 (device.is_screen_locked)](device.is_screen_locked.md)
- [获取前台应用的画面方向 (device.front_orien)](device.front_orien.md)
- [锁定设备屏幕旋转 (device.lock_orien)](device.lock_orien.md)
- [解锁设备屏幕旋转锁 (device.unlock_orien)](device.unlock_orien.md)
- [获取屏幕旋转锁锁定状态 (device.is_orien_locked)](device.is_orien_locked.md)
- [振动设备 (device.vibrator)](device.vibrator.md)
- [后台播放声音 (device.play_sound)](device.play_sound.md)
- [获取设备类型 (device.type)](device.type.md)
- [获取设备名 (device.name)](device.name.md)
- [设置设备名 (device.set_name)](device.set_name.md)
- [获取设备 UDID (device.udid)](device.udid.md)
- [获取设备的序列号 (device.serial_number)](device.serial_number.md)
- [获取设备的 WiFi MAC 地址 (device.wifi_mac)](device.wifi_mac.md)
- [获取当前 Wi-Fi 的信息 (device.wifi_info)](device.wifi_info.md)
- [获取设备所有的接口 IP (device.ifaddrs)](device.ifaddrs.md)
- [获取当前设备电池剩余电量 (device.battery_level)](device.battery_level.md)
- [获取当前设备充电状态 (device.battery_state)](device.battery_state.md)
- [打开设备 WiFi (device.turn_on_wifi)](device.turn_on_wifi.md)
- [关闭设备 WiFi (device.turn_off_wifi)](device.turn_off_wifi.md)
- [打开设备蜂窝数据 (device.turn_on_data)](device.turn_on_data.md)
- [关闭设备蜂窝数据 (device.turn_off_data)](device.turn_off_data.md)
- [打开设备蓝牙 (device.turn_on_bluetooth)](device.turn_on_bluetooth.md)
- [关闭设备蓝牙 (device.turn_off_bluetooth)](device.turn_off_bluetooth.md)
- [打开设备飞行模式 (device.turn_on_airplane)](device.turn_on_airplane.md)
- [关闭设备飞行模式 (device.turn_off_airplane)](device.turn_off_airplane.md)
- [连接到当前设置所选 VPN (device.turn_on_vpn)](device.turn_on_vpn.md)
- [断开已有的 VPN 连接 (device.turn_off_vpn)](device.turn_off_vpn.md)
- [判断当前是否打开了 VPN 开关 (device.is_vpn_on)](device.is_vpn_on.md)
- [打开设备闪光灯 (device.flash_on)](device.flash_on.md)
- [关闭设备闪光灯 (device.flash_off)](device.flash_off.md)
- [打开“减少动态效果”开关 (device.reduce_motion_on)](device.reduce_motion_on.md)
- [关闭“减少动态效果”开关 (device.reduce_motion_off)](device.reduce_motion_off.md)
- [打开 AssistiveTouch (device.assistive_touch_on)](device.assistive_touch_on.md)
- [关闭 AssistiveTouch (device.assistive_touch_off)](device.assistive_touch_off.md)
- [获取背光亮度值 (device.brightness)](device.brightness.md)
- [设置背光亮度 (device.set_brightness)](device.set_brightness.md)
- [设置自动锁屏分钟数 (device.set_autolock_time)](device.set_autolock_time.md)
- [设置设备音量 (device.set_volume)](device.set_volume.md)
- [! 加入到一个无线局域网 (device.join_wifi)](device.join_wifi.md)
- [遗忘一个无线局域网 (device.forget_wifi)](device.forget_wifi.md)

---

Source: [图片对象模块 (image)](https://xxtouch.app/docs/handbook/image/index.md)
Path: handbook/image/README.md

# 图片对象模块 (image)

---

- [判断一个值是否是图片对象 (image.is)](image.is.md)
- [创建指定尺寸空白图片对象 (image.new)](image.new.md)
- [图像合并 (image.oper_merge)](image.oper_merge.md)
- [新建一个文本图片对象 (image.new_text_image)](image.new_text_image.md)
- [从文件创建图片对象 (image.load_file)](image.load_file.md)
- [从数据创建图片对象 (image.load_data)](image.load_data.md)
- [从图片对象创建拷贝图片对象 (:copy)](imagem_copy.md)
- [从图片对象截取部分新建拷贝图片对象 (:crop)](imagem_crop.md)
- [保存图片对象到相册 (:save_to_album)](imagem_save_to_album.md)
- [输出图片对象到一个 PNG 格式的文件 (:save_to_png_file)](imagem_save_to_png_file.md)
- [输出图片对象到一个 JPEG 格式的文件 (:save_to_jpeg_file)](imagem_save_to_jpeg_file.md)
- [获取图片对象的 PNG 格式数据 (:png_data)](imagem_png_data.md)
- [获取图片对象的 JPEG 格式数据 (:jpeg_data)](imagem_jpeg_data.md)
- [90 度左旋图片对象 (:turn_left)](imagem_turn_left.md)
- [90 度右旋图片对象 (:turn_right)](imagem_turn_right.md)
- [获取图片对象的尺寸 (:size)](imagem_size.md)
- [获取图片对象某点颜色 (:get_color)](imagem_get_color.md)
- [设置图片对象某点颜色 (:set_color)](imagem_set_color.md)
- [颜色替换 (:replace_color)](imagem_replace_color.md)
- [图中贴图 (:draw_image)](imagem_draw_image.md)
- [二值化处理图片对象 (:binaryzation)](imagem_binaryzation.md)
- [图片多点颜色匹配 (:is_colors)](imagem_is_colors.md)
- [图中找色 (:find_color)](imagem_find_color.md)
- [图中找图 (:find_image)](imagem_find_image.md)
- [! 图片文字识别 (:ocr_text)](imagem_ocr_text.md)
- [解码一个二维码图片 (:qr_decode)](imagem_qr_decode.md)
- [销毁一个图片对象 (:destroy)](imagem_destroy.md)
- [cv - 图中找图 (:cv_find_image)](imagem_cv_find_image.md)
- [cv - 图片自动二值化 (:cv_binaryzation)](imagem_cv_binaryzation.md)
- [cv - 从图片创建一个拉伸的另外尺寸的图片 (:cv_resize)](imagem_cv_resize.md)
- [cv - 图片对比 (:cv_compare_image)](imagem_cv_compare_image.md)
- [cv - 图片转换成形状轮廓信息 (:cv_to_shapes)](imagem_cv_to_shapes.md)
- [cv - 从图片找轮廓 (:cv_find_shapes)](imagem_cv_find_shapes.md)
- [cv - 图片多模板特征检测 (:cv_detect_templates)](imagem_cv_detect_templates.md)

---

Source: [CoreML 模块 (coreml)](https://xxtouch.app/docs/handbook/coreml/index.md)
Path: handbook/coreml/README.md

# CoreML 模块 (coreml)

**软件版本在 1.3.8 或以上方可使用**
CoreML 模块用于在设备上进行机器学习推理。除了 Vision 视觉推理器外，还支持：

- 通用模型 request / session
- `MLMultiArray` 创建、转换与运算
- 图像与张量互转
- 可按类型分发的文本分词器
- 检测 / OBB / mask / keypoint / tracker 等通用后处理辅助

SentencePiece 采用面向端侧推理的轻量兼容实现，支持 `.vocab` 和 `.model` 两种输入来源。`require("onnxruntime")` 之后，还会额外注入 `MLMultiArray` 与 ORT tensor 的原生拷贝转换接口。

## 平台支持说明

CoreML 模块整体以 **iOS 11+** 为基础，但不同接口的最低系统版本并不完全相同：

- `new_model_request` / `session`、`MLMultiArray` 相关接口、图像张量化、tokenizer、绝大多数几何 / 后处理辅助：**iOS 11+**
- `compile_model`、`new_vision_request`、`predict_batch()` / `run_batch()`、`compute_units` 创建与查询：**iOS 12+**
- 在通用 model request 里把 `image_object` 作为 image feature 输入：**iOS 13+**
- `class_labels()`：**iOS 14+**
- `compute_units = "cpu_and_neural_engine"`：**iOS 16+**

---

- [本机编译 CoreML 模型](coreml.compile_model.md)
- [创建一个 CoreML 视觉推理器](coreml.new_vision_request.md)
- [! 使用 CoreML 视觉推理器对图像进行推理](coreml_vision_request_objectm_predict.md)
- [创建一个通用 CoreML 推理器](coreml.new_model_request.md)
- [CoreML 通用推理器对象方法](coreml_model_request_object_methods.md)
- [ML 多维数组模块](coreml.multi_array_module.md)
- [文本分词器模块](coreml.tokenizer_module.md)
- [ONNX Runtime 模块 (onnxruntime)](../onnxruntime/README.md)

## 额外说明

- `coreml.session(...)` 是 `coreml.new_model_request(...)` 的别名
- `coreml.tensor(...)` 是 `coreml.new_multi_array(...)` 的别名
- `coreml.tensor_from_table(...)` 是 `coreml.multi_array_from_table(...)` 的别名
- `coreml.image_to_multi_array(...)` 仍然可用，但现在只是 `coreml.tensor_from_image(...)` 的兼容别名
- `coreml.multi_array_from_quad(...)` 是 `coreml.tensor_from_quad(...)` 的别名
- `coreml.multi_array_from_quads(...)` 是 `coreml.tensor_from_quads(...)` 的别名
- `coreml.project_masks(...)` 是 `coreml.proto_masks(...)` 的别名

---

Source: [ONNX Runtime 模块 (onnxruntime)](https://xxtouch.app/docs/handbook/onnxruntime/index.md)
Path: handbook/onnxruntime/README.md

# ONNX Runtime 模块 (onnxruntime)

> **该模块在 20260402 以后版本方可使用**
> **仅支持 iOS 13 及以上版本系统**

`onnxruntime` 模块用于在设备上直接加载和运行 ONNX 模型，适合文本、Embedding、分类、检测以及各种通用张量推理场景。

## 加载模块

```lua
local ort = require("onnxruntime")
```

这是一个按需加载模块，不像 `coreml` 那样是内置全局模块。

当 `require("onnxruntime")` 成功执行后，还会向内置 `coreml` 模块注入两组桥接接口：

- `coreml.multi_array_from_ort_tensor(tensor[, data_type])`
- `multi_array:to_ort_tensor([data_type])`

这两组转换都在 native 层直接拷贝，不经过 Lua table。

## 模块级函数

### 运行时与基础信息

- `onnxruntime.version()`
- `onnxruntime.providers()`
- `onnxruntime.configure(opts)`

说明：

- `providers()` 返回当前 ORT 运行时实际可用的 Execution Provider 列表
- `configure()` 用于设置全局运行时默认值，**必须在创建任何 session 之前调用**

### 张量、图像与数值辅助

- `onnxruntime.tensor(type, shape[, data])`
- `onnxruntime.tensor_from_bytes(type, shape, bytes)`
- `onnxruntime.tensor_from_cv_mat(mat[, opts])`
- `onnxruntime.tensor_from_quad(mat, quad[, opts])`
- `onnxruntime.tensor_from_quads(mat, quads[, opts])`
- `onnxruntime.tensor_from_image(image[, opts])`
- `onnxruntime.tensor_from_images(images[, opts])`
- `onnxruntime.image_from_tensor(tensor[, opts])`
- `onnxruntime.clamp(tensor, min, max)`
- `onnxruntime.sigmoid(tensor)`
- `onnxruntime.exp(tensor)`
- `onnxruntime.where(condition, x, y)`
- `onnxruntime.matmul(lhs, rhs)`
- `onnxruntime.concat(tensors[, axis])`
- `onnxruntime.stack(tensors[, axis])`

说明：

- `clamp()`、`sigmoid()`、`exp()`、`matmul()` 与同名 `tensor:` 方法等价，只是把 tensor 作为第一个参数传入
- `where()` 支持标量 / 布尔值 / tensor 混用，并按广播规则生成结果
- 图像预处理、OpenCV 桥接和 `image_from_tensor()` 的细节，详见 [张量模块](onnxruntime.tensor_module.md)

### 检测、解码与后处理辅助

- `onnxruntime.nms(boxes, scores[, opts])`
- `onnxruntime.box_points(rotated_boxes)`
- `onnxruntime.xywh_to_xyxy(boxes)`
- `onnxruntime.xyxy_to_xywh(boxes)`
- `onnxruntime.rotated_iou(lhs_box, rhs_box)`
- `onnxruntime.rotated_nms(boxes, scores[, opts])`
- `onnxruntime.create_decoder(schema)`
- `onnxruntime.decode_yolo(output[, opts])`
- `onnxruntime.decode_yolo_obb(output[, opts])`
- `onnxruntime.decode_matrix_candidates(output, schema[, opts])`
- `onnxruntime.decode_dense_detection(output, opts)`
- `onnxruntime.records_from_boxes(boxes, scores, class_ids[, keep_indices])`
- `onnxruntime.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])`
- `onnxruntime.points_to_records(points[, opts])`
- `onnxruntime.threshold_masks(masks, threshold)`
- `onnxruntime.crop_masks_by_boxes(masks, boxes)`
- `onnxruntime.resize_masks(masks, width, height[, opts])`
- `onnxruntime.mask_iou(lhs_mask, rhs_mask)`
- `onnxruntime.mask_to_polygon(mask[, opts])`
- `onnxruntime.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])`
- `onnxruntime.project_masks(proto, coeffs, boxes, image_width, image_height[, opts])`
- `onnxruntime.db_postprocess(score_map[, opts])`
- `onnxruntime.tracker([opts])`
- `onnxruntime.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])`
- `onnxruntime.scale_boxes(boxes, transform)`
- `onnxruntime.clip_boxes(boxes, clip_width, clip_height)`
- `onnxruntime.scale_points(points, transform[, opts])`
- `onnxruntime.scale_keypoints(points, transform[, opts])`
- `onnxruntime.clip_keypoints(points, clip_width, clip_height[, opts])`
- `onnxruntime.ctc_greedy_decode(logits[, opts])`
- `onnxruntime.sample_logits(logits[, opts])`

说明：

- `tensor_from_quad()` / `tensor_from_quads()` 需要先 `require("image.cv")`，适合 OCR 四边形裁剪后直接生成张量
- `box_points()` 接收形状为 `[5]`、`[1, 5]` 或 `[N, 5]` 的旋转框 tensor，不是五个分离标量参数
- `create_decoder()` 返回 decoder 对象，支持 `:decode()`、`:task()`、`:schema()`
- `tracker()` 返回 tracker 对象，支持 `:update()`、`:reset()`、`:state()`、`:close()`
- `records_from_boxes()`、`obb_records_from_rows()`、`points_to_records()` 会把 tensor 结果整理成更适合 Lua 侧消费的 record table
- `proto_masks()` 与 `project_masks()` 当前是同一套实现，后者只是别名
- `mask_iou()` 用于直接计算两张 mask 的交并比，也支持第三个参数 `opts`，可传 `compare_size = true`，或显式传 `width` / `height`
- `db_postprocess()` 适合 DB / DBNet 一类文本检测后处理；返回的每个检测项都带 `score`、`points` 和 `box`
- `decode_dense_detection()` 要求 `opts.strides` 为非空正整数数组，并且还需要 `decode_width`、`decode_height`；当前只支持 `box_encoding = "grid_center_log_wh"`
- `ctc_greedy_decode()` 支持 `blank_index`、`merge_repeated`、`apply_softmax`、`return_probabilities`、`charset`
- `ctc_greedy_decode()` 一定返回 `indices`；`text` 仅在传入 `charset` 时返回；`confidence` 仅在启用 `apply_softmax` 或 `return_probabilities` 时返回；`probabilities` 与 `probability_confidence` 仅在启用 `return_probabilities` 时返回
- `nms()` / `rotated_nms()` 返回的是 `int64` tensor，索引语义为 **1-based**
- `sample_logits()` 支持 `argmax`、`temperature`、`top_k`、`top_p`、`min_p`、`seed`
- `sample_logits()` 对 1D logits 返回单个索引；对 batched logits 返回 `int64` tensor

### 结构化值

- `onnxruntime.value(value)`
- `onnxruntime.optional(value, type_info)`
- `onnxruntime.sequence(items)`
- `onnxruntime.map(key_type, value_type, pairs)`
- `onnxruntime.sparse_tensor(type, dense_shape, indices, values)`
- `onnxruntime.sparse_tensor_from_dense(tensor)`

适合处理非纯 tensor 的输入输出，例如 optional、sequence、map 和 sparse tensor。

当前行为可以概括为：

- `onnxruntime.value(x)`
  如果 `x` 已经是 ORT tensor / value / sequence / map / sparse tensor，则原样返回；如果 `x` 是 Lua table，则按 `sequence` 处理；否则会把标量包装成 tensor
- `onnxruntime.optional(value, type_info)`
  第二个参数必填；`type_info` 可以是字符串，也可以直接传 `session:input_info(...)` / `output_info(...)` 返回的类型信息表；空 optional 用 `onnxruntime.optional(nil, type_info)` 表示
- `onnxruntime.map(key_type, value_type, pairs)`
  当前 `key_type` 仅支持 `"string"` 或 `"int64"`
- `onnxruntime.sparse_tensor(type, dense_shape, indices, values)`
  当前只支持数值 / `bool` 稀疏张量，按 COO 方式构造；`indices` 可以是扁平数组，也可以是坐标数组
- `onnxruntime.sparse_tensor_from_dense(tensor)`
  当前不支持 `string` tensor

常用对象方法：

- `value:type()` / `value:has_value()` / `value:get()`
- `sequence:length()` / `sequence:get(i)` / `sequence:items()`
- `map:get(key)` / `map:set(key, value)` / `map:keys()` / `map:pairs()`
- `sparse_tensor:dense_shape()` / `sparse_tensor:values()` / `sparse_tensor:indices()` / `sparse_tensor:format()` / `sparse_tensor:to_dense()`

### 会话与推理

- `onnxruntime.session(model_path[, opts])`
- `onnxruntime.session_from_bytes(model_bytes[, opts])`
- `onnxruntime.run_options([opts])`
- `onnxruntime.load_custom_op_library(path)`

会话对象负责模型加载、输入输出信息查询、执行推理以及 `IOBinding`。详见 [会话模块](onnxruntime.session_module.md)。

## 支持的数据类型

当前张量接口支持以下元素类型名称：

- `"float32"` / `"float"`
- `"float16"`
- `"bfloat16"`
- `"uint8"`
- `"uint16"`
- `"uint32"`
- `"uint64"`
- `"int8"`
- `"int16"`
- `"int32"`
- `"int64"`
- `"double"` / `"float64"`
- `"bool"`
- `"string"`

说明：

- `tensor_from_bytes()` 和 `copy_from_bytes()` 只支持数值和 `bool` 类型
- `bytes()` 不支持 `string` tensor
- `tensor:to("string")` 目前只支持 `string -> string`

## Provider 说明

`onnxruntime.providers()` 会返回运行时可见的 provider 列表，但当前 session 选项里原生处理并支持的 provider 字符串是：

- `"cpu"`
- `"coreml"`

说明：

- `provider` / `providers` 也接受 `CPUExecutionProvider`、`CoreMLExecutionProvider` 这类别名，内部会归一化到 `"cpu"`、`"coreml"`
- 如果没有显式指定 provider，或 provider 列表为空，session 创建阶段会自动补上 CPU provider
- 如果 provider 列表里包含 `"coreml"` 且 `fallback_to_cpu = true`，实现也可能补上 CPU 作为回退路径
- 如果你传入 `providers = {"coreml", "cpu"}`，表示优先尝试 CoreML，再尝试 CPU

## 与 CoreML 联动

如果你要复用 `coreml` 分词器或 `MLMultiArray` 预处理流程，推荐这样组合：

```lua
local ort = require("onnxruntime")

local tokenizer = assert(coreml.new_text_tokenizer({
    type = "wordpiece",
    vocab_path = XXT_HOME_PATH.."/models/demo/vocab.txt",
    context_length = 52,
}))

local input_ids = assert(tokenizer:encode("hello", {
    output = "ort_tensor",
}))
```

或者把已有的 `MLMultiArray` 直接转成 ORT tensor：

```lua
local ort = require("onnxruntime")
local tensor = assert(multi_array:to_ort_tensor("int64"))
```

---

Source: [进程字典相关函数](https://xxtouch.app/docs/handbook/proc/index.md)
Path: handbook/proc/README.md

# 进程字典相关函数

---

- [存储值到进程字典 (proc_put)](proc_put.md)
- [查看进程字典存储的值 (proc_get)](proc_get.md)
- [向进程队列词典中压入一个值 (proc_queue_push)](proc_queue_push.md)
- [从进程队列词典中弹出一个值 (proc_queue_pop)](proc_queue_pop.md)
- [从进程队列词典中弹出所有值 (proc_queue_clear)](proc_queue_clear.md)
- [读取进程队列词典中所有的值 (proc_queue_read)](proc_queue_read.md)
- [获取进程队列词典的尺寸 (proc_queue_size)](proc_queue_size.md)
- [向进程队列词典头部压入一个值 (proc_queue_push_front)](proc_queue_push_front.md)
- [向进程队列词典尾部压入一个值 (proc_queue_push_back)](proc_queue_push_back.md)
- [从进程队列词典头部弹出一个值 (proc_queue_pop_front)](proc_queue_pop_front.md)
- [从进程队列词典尾部弹出一个值 (proc_queue_pop_back)](proc_queue_pop_back.md)
- [从进程队列词典中弹出特定值 (proc_queue_pop_value)](proc_queue_pop_value.md)
- [统计进程队列词典特定值个数 (proc_queue_count_value)](proc_queue_count_value.md)
- [执行进程词典事务代码 (proc_dict_run)](proc_dict_run.md)

---

Source: [线程模块 (thread)](https://xxtouch.app/docs/handbook/thread/index.md)
Path: handbook/thread/README.md

# 线程模块 (thread)

thread 模块基于 Lua 自带的协程（coroutine）实现，并非通常意义上的多线程。

---

- [派发一个任务 (thread.dispatch)](thread.dispatch.md)
- [获取当前任务的 ID (thread.current_id)](thread.current_id.md)
- [从队列中移除一项任务 (thread.kill)](thread.kill.md)
- [阻塞等待另一个任务完成 (thread.wait)](thread.wait.md)
- [注册监听一个事件 (thread.register_event)](thread.register_event.md)
- [反注册监听一个事件 (thread.unregister_event)](thread.unregister_event.md)
- [thread 示例代码](samples.md)

---

Source: [Web 视图模块 (webview)](https://xxtouch.app/docs/handbook/webview/index.md)
Path: handbook/webview/README.md

# Web 视图模块 (webview)

> **在 iOS 16 及以上版本系统中，该模块仅在巨魔版 XXTouch 中有效**

---

- [展现一个 webview (webview.show)](webview.show.md)
- [隐藏一个 webview (webview.hide)](webview.hide.md)
- [在一个 webview 上执行一段 JS (webview.eval)](webview.eval.md)
- [获取一个 webview 的区域及层级信息 (webview.frame)](webview.frame.md)
- [销毁一个 webview (webview.destroy)](webview.destroy.md)
- [webview 使用示例](samples.md)

---

Source: [XPP 脚本包模块 (xpp)](https://xxtouch.app/docs/handbook/xpp/index.md)
Path: handbook/xpp/README.md

# XPP 脚本包模块 (xpp)

**XPP**（以下称"脚本应用包"）是可被 XXTouch 解析、查看与执行的一种 Bundle（包）结构，以单一文件的形式呈现给用户。这个"文件"实际上是一个以 **.xpp** 为扩展名的目录（文件夹）

脚本包格式标准参考 [XPP 格式](/docs/XPP/Layout.md)

---

- [获取当前脚本包的元信息 (xpp.info)](xpp.info.md)
- [获取当前脚本包的包路径 (xpp.bundle_path)](xpp.bundle_path.md)
- [获取当前脚本包中的资源路径 (xpp.resource_path)](xpp.resource_path.md)

---

Source: [XUI 脚本配置界面模块 (xui)](https://xxtouch.app/docs/handbook/xui/index.md)
Path: handbook/xui/README.md

# XUI 脚本配置界面模块 (xui)

XUI 用于在 XXTouch 上提供配置界面，采用 iOS 系统原生组件。本手册提供了 XUI 界面布局的规范。XUI 是 [XPP 脚本包](/docs/XPP/index.md) 的一部分，用来为脚本包创建配置，不能独立使用。

脚本配置界面参考 [XUI 格式](/XUI/START.md)

---

- [展示一个配置界面 (xui.show)](xui.show.md)
- [收起正在展示的配置界面 (xui.dismiss)](xui.dismiss.md)
- [校验配置界面的配置 (xui.setup)](xui.setup.md)
- [重新加载当前正在展示的配置界面 (xui.reload)](xui.reload.md)
- [获取配置界面的配置值 (xui.get)](xui.get.md)
- [设置配置界面上的某个控件的值 (xui.set)](xui.set.md)
- [读取某个配置分区所有配置 (xui.read)](xui.read.md)
- [覆盖写入配置表到某个配置分区 (xui.write)](xui.write.md)
- [清除某个配置分区所有的配置 (xui.clear)](xui.clear.md)

---

Source: [扩展 table 模块 (table)](https://xxtouch.app/docs/handbook/ext-table/index.md)
Path: handbook/ext-table/README.md

# 扩展 table 模块 (table)

[table](https://cloudwu.github.io/lua53doc/manual.html#6.6) 模块是 Lua 基础模块，XXTouch 在其基础上做了一些扩展。

---

- [深拷贝一个表 (table.deep_copy)](table.deep_copy.md)
- [深序列化一个表 (table.deep_dump)](table.deep_dump.md)
- [从序列化文本加载一个表 (table.load_string)](table.load_string.md)

---

Source: [扩展 string 模块 (string)](https://xxtouch.app/docs/handbook/ext-string/index.md)
Path: handbook/ext-string/README.md

# 扩展 string 模块 (string)

[string](https://cloudwu.github.io/lua53doc/manual.html#6.4) 模块是 Lua 基础模块，XXTouch 在其基础上做了一些扩展。

---

- [转成 16 进制文本 (string.to_hex)](string.to_hex.md)
- [从 16 进制文本转回 (string.from_hex)](string.from_hex.md)
- [将 GBK 编码的文本转成 UTF-8 编码的文本 (string.from_gbk)](string.from_gbk.md)
- [计算字符串的 md5 哈希值 (string.md5)](string.md5.md)
- [计算字符串的 sha1 哈希值 (string.sha1)](string.sha1.md)
- [计算字符串的 HMAC-SHA1 哈希值 (string.hmac_sha1)](string.hmac_sha1.md)
- [计算字符串的 HMAC-SHA256 哈希值 (string.hmac_sha256)](string.hmac_sha256.md)
- [对字符串进行 base64 编码 (string.base64_encode)](string.base64_encode.md)
- [对 base64 编码的文本进行解码 (string.base64_decode)](string.base64_decode.md)
- [对 URI 进行编码 (string.encode_uri)](string.encode_uri.md)
- [对 URI 进行解码 (string.decode_uri)](string.decode_uri.md)
- [对 URI 组件进行编码 (string.encode_uri_component)](string.encode_uri_component.md)
- [对 URI 组件进行解码 (string.decode_uri_component)](string.decode_uri_component.md)
- [对字符串进行加密 (string.aes128_encrypt)](string.aes128_encrypt.md)
- [解密一段已加密的字符串 (string.aes128_decrypt)](string.aes128_decrypt.md)
- [用分隔符规则分割一个字符串 (string.split)](string.split.md)
- [去除文本左边空白字符 (string.ltrim)](string.ltrim.md)
- [去除文本右边空白字符 (string.rtrim)](string.rtrim.md)
- [去除文本左右两边空白字符 (string.trim)](string.trim.md)
- [去除文本中所有的空白字符 (string.atrim)](string.atrim.md)
- [去除掉文本前的 UTF8-BOM (string.strip_utf8_bom)](string.strip_utf8_bom.md)
- [生成随机字符串 (string.random)](string.random.md)
- [比较两个版本号大小 (string.compare_version)](string.compare_version.md)
- [判断字符串起始于 (string.starts_with)](string.starts_with.md)
- [判断字符串结束于 (string.ends_with)](string.ends_with.md)
- [左填充字符串 (string.lpad)](string.lpad.md)
- [右填充字符串 (string.rpad)](string.rpad.md)
- [扩展 string 示例代码](samples.md)

---

Source: [! HTTP 模块 (http)](https://xxtouch.app/docs/handbook/http/index.md)
Path: handbook/http/README.md

# ! HTTP 模块 (http)

当前模块不支持 HTTP/1.0 或更低版本的协议。若无法满足需求，可改用 [`lcurl 模块`](/docs/handbook/open-source/lcurl.md) 来实现。

---

- [发起 GET 请求 (http.get)](http.get.md)
- [发起 POST 请求 (http.post)](http.post.md)
- [HTTP 文件下载 (http.download)](http.download.md)
- [发起 HEAD 请求 (http.head)](http.head.md)
- [发起 DELETE 请求 (http.delete)](http.delete.md)
- [发起 PUT 请求 (http.put)](http.put.md)
- [编码 HTTP URLENCODED 表单 (http.table_to_form_urlencoded)](http.table_to_form_urlencoded.md)

---

Source: [! FTP 模块 (ftp)](https://xxtouch.app/docs/handbook/ftp/index.md)
Path: handbook/ftp/README.md

# ! FTP 模块 (ftp)

---

- [FTP 文件下载 (ftp.download)](ftp.download.md)
- [FTP 文件上传 (ftp.upload)](ftp.upload.md)
- [FTP 执行命令 (ftp.cmd)](ftp.cmd.md)

---

Source: [JSON 模块 (json)](https://xxtouch.app/docs/handbook/json/index.md)
Path: handbook/json/README.md

# JSON 模块 (json)

JSON（JavaScript Object Notation，JS 对象标记）是一种轻量级的数据交换格式。详情参见：https://www.json.org/

该 JSON 模块完全等同于 [LuaCJSON 扩展库](/docs/handbook/open-source/luacjson.md)，非原创模块。

---

- [将 Lua 值转成 JSON 字符串 (json.encode)](json.encode.md)
- [将 JSON 字符串转换成 Lua 值 (json.decode)](json.decode.md)
- [JSON 中的 NULL 常量 (json.null)](json.null.md)

---

Source: [PLIST 读写模块 (plist)](https://xxtouch.app/docs/handbook/plist/index.md)
Path: handbook/plist/README.md

# PLIST 读写模块 (plist)

---

- [读取属性表文件 (plist.read)](plist.read.md)
- [写入属性表文件 (plist.write)](plist.write.md)
- [读取属性表数据 (plist.load)](plist.load.md)
- [取 Lua 表的属性表数据 (plist.dump)](plist.dump.md)
- [属性表数据格式转换 (plist.data_convert)](plist.data_convert.md)

---

Source: [小工具模块 (utils)](https://xxtouch.app/docs/handbook/utils/index.md)
Path: handbook/utils/README.md

# 小工具模块 (utils)

---

- [! 给通讯录添加一个或多个联系人 (utils.add_contacts)](utils.add_contacts.md)
- [删除通讯录所有联系人 (utils.remove_all_contacts)](utils.remove_all_contacts.md)
- [将文本编码成二维码图片 (utils.qr_encode)](utils.qr_encode.md)
- [获得当前脚本的启动参数 (utils.launch_args)](utils.launch_args.md)
- [判断当前脚本是否从 App 内启动 (utils.is_launch_via_app)](utils.is_launch_via_app.md)
- [导入一个视频文件到相册 (utils.video_to_album)](utils.video_to_album.md)
- [生成一个 UUID (utils.gen_uuid)](utils.gen_uuid.md)
- [生成基于时间的一次性验证码 (utils.totp_next)](utils.totp_next.md)
- [按计数器生成一次性验证码 (utils.hotp_counter)](utils.hotp_counter.md)
- [生成下一个基于计数器的一次性验证码 (utils.hotp_next)](utils.hotp_next.md)
- [时间戳转换为 RFC 1123 格式文本 (utils.date_to_rfc1123)](utils.date_to_rfc1123.md)
- [RFC 1123 格式的时间文本转换为时间戳 (utils.date_from_rfc1123)](utils.date_from_rfc1123.md)
- [时间戳转换为 RFC 3339 格式文本 (utils.date_to_rfc3339)](utils.date_to_rfc3339.md)
- [RFC 3339 格式的时间文本转换为时间戳 (utils.date_from_rfc3339)](utils.date_from_rfc3339.md)
- [时间戳转换为格式的时间文本 (utils.date_to_format)](utils.date_to_format.md)
- [格式的时间文本转换为时间戳 (utils.date_from_format)](utils.date_from_format.md)

---

Source: [文件操作模块 (file)](https://xxtouch.app/docs/handbook/file/index.md)
Path: handbook/file/README.md

# 文件操作模块 (file)

---

- [判断一个文件或目录是否存在 (file.exists)](file.exists.md)
- [获取目录所有文件名列表 (file.list)](file.list.md)
- [获得一个文件的尺寸 (file.size)](file.size.md)
- [读取一个文件中的所有数据 (file.reads)](file.reads.md)
- [将数据覆盖写入到文件 (file.writes)](file.writes.md)
- [将数据追加到文件末尾 (file.appends)](file.appends.md)
- [统计一个文本文件的总行数 (file.line_count)](file.line_count.md)
- [获取一个文本文件指定行的数据 (file.get_line)](file.get_line.md)
- [设置文本文件指定行的内容 (file.set_line)](file.set_line.md)
- [在文本文件指定行前插入内容 (file.insert_line)](file.insert_line.md)
- [移除文件中指定行 (file.remove_line)](file.remove_line.md)
- [获取一个文本文件的所有行 (file.get_lines)](file.get_lines.md)
- [将一个顺序表转换逐行覆盖写入到文件中 (file.set_lines)](file.set_lines.md)
- [将一个顺序表转换逐行插入到文件指定行前 (file.insert_lines)](file.insert_lines.md)
- [获得一个文件的 MD5 值 (file.md5)](file.md5.md)
- [获得一个文件的 SHA1 值 (file.sha1)](file.sha1.md)
- [删除文件或目录 (file.remove)](file.remove.md)
- [移动文件或目录 (file.move)](file.move.md)
- [拷贝文件或目录 (file.copy)](file.copy.md)
- [查找文件或目录 (file.find)](file.find.md)
- [切换当前工作目录 (file.chdir)](file.chdir.md)
- [获取当前工作目录 (file.currentdir)](file.currentdir.md)
- [获取文件属性 (file.attrs)](file.attrs.md)
- [获取符号链接属性 (file.lattrs)](file.lattrs.md)
- [创建文件链接 (file.link)](file.link.md)
- [递归创建目录 (file.mkdir_p)](file.mkdir_p.md)
- [更新文件访问和修改时间 (file.touch)](file.touch.md)
- [使用 ZIP 打包一些文件 (file.zip)](file.zip.md)
- [解压 ZIP 文件 (file.unzip)](file.unzip.md)
- [分解路径组成部分 (file.path.components)](file.path.components.md)
- [获取路径的最后一个组成部分 (file.path.last_component)](file.path.last_component.md)
- [删除路径的最后一个组成部分 (file.path.remove_last_component)](file.path.remove_last_component.md)
- [追加路径组成部分 (file.path.add_component)](file.path.add_component.md)
- [获取路径的文件扩展名 (file.path.extension)](file.path.extension.md)
- [删除路径的文件扩展名 (file.path.remove_extension)](file.path.remove_extension.md)
- [追加文件扩展名 (file.path.add_extension)](file.path.add_extension.md)
- [标准化路径 (file.path.normalize)](file.path.normalize.md)
- [解析路径中的符号链接 (file.path.resolve_symlinks)](file.path.resolve_symlinks.md)

---

Source: [VPN 配置模块 (vpnconf)](https://xxtouch.app/docs/handbook/vpnconf/index.md)
Path: handbook/vpnconf/README.md

# VPN 配置模块 (vpnconf)

---

- [创建一个 VPN 配置 (vpnconf.create)](vpnconf.create.md)
- [获取当前系统 VPN 的列表 (vpnconf.list)](vpnconf.list.md)
- [选择一个 VPN 配置 (vpnconf.select)](vpnconf.select.md)
- [删除一个 VPN 配置 (vpnconf.delete)](vpnconf.delete.md)
- [以当前选择的 VPN 建立连接 (vpnconf.connect)](vpnconf.connect.md)
- [断开当前的 VPN 连接 (vpnconf.disconnect)](vpnconf.disconnect.md)
- [获取当前选择的 VPN 的状态 (vpnconf.status)](vpnconf.status.md)

---

Source: [系统回调消息](https://xxtouch.app/docs/handbook/system-callback/index.md)
Path: handbook/system-callback/README.md

# 系统回调消息

**本章没有自定义函数**

---

- [电话呼入呼出回调消息](call.md)
- [Activator 事件回调消息](activator.md)
- [HID 事件消息](hid.md)

---

Source: [已集成的开源扩展库](https://xxtouch.app/docs/handbook/open-source/index.md)
Path: handbook/open-source/README.md

# 已集成的开源扩展库

---

- [LuaCJSON 扩展库](luacjson.md)
- [LuaSocket 扩展库](luasocket.md)
- [luaiconv 编码转换扩展库](luaiconv.md)
- [lpeg 扩展库](lpeg.md)
- [LuaFileSystem 扩展库](luafilesystem.md)
- [LuaSQLite3 模块](luasqlite3.md)
- [lcurl 模块](lcurl.md)
- [lunix 模块](lunix.md)
- [lua-openssl 扩展库](lua-openssl.md)

---

Source: [附录](https://xxtouch.app/docs/handbook/supplement/index.md)
Path: handbook/supplement/README.md

# 附录

---

- [开发及周边工具下载](dev-tools.md)
- [扩展库及远程扩展接口](exts.md)
- [脚本守护模式是什么？](daemon-mode.md)
- [开机启动的时机说明](bootstrap.md)
- ["URL Scheme" 的相关应用](url-scheme.md)
- [日期格式化相关 (os.date)](os.date.md)
- [命令执行相关示例代码 (os.execute)](os.execute.md)
- [string 库的相关应用](string-samples.md)
- [math 库的相关应用](math-samples.md)
- [学习 Lua 应当注意的](abc.md)
- [开发常见运行期错误参考](runtime-errors.md)

---

Source: [获取 App 的应用程序包路径 (app.bundle_path)](https://xxtouch.app/docs/handbook/app/app.bundle_path.md)
Path: handbook/app/app.bundle_path.md

# 获取 App 的应用程序包路径 (app.bundle_path)


## 声明

```lua
包路径 = app.bundle_path(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 包路径
    文本型 或 nil，返回的应用程序包路径，如果应用不存在则返回 nil


## 说明

> 获取 App 的应用程序包路径


## 示例

```lua
path = app.bundle_path("com.tencent.mqq") -- 获得 QQ 的应用包路径
```

---

Source: [清理某个或某组钥匙串信息 (clear.keychain)](https://xxtouch.app/docs/handbook/clear/clear.keychain.md)
Path: handbook/clear/clear.keychain.md

# 清理某个或某组钥匙串信息 (clear.keychain)


## 声明

```lua
clear.keychain(信息关联名)
```


## 参数

- 信息关联名
    文本型，一般传入公司反域名或应用程序的 TeamID，例如 `"com.doglobal"` 或 `"GN26HFBMX6"`


## 说明

> 清理某个应用程序或分组的钥匙串信息；若不熟悉其含义，请改用 [`clear.all_keychain`](/docs/handbook/clear/clear.all_keychain.md)
> **警告：该函数调用的效果不可逆**
> **警告：切勿随意传入参数，错误参数可能造成极其严重的后果**


## 示例

```lua
clear.keychain("com.doglobal") -- 清理掉与 com.doglobal 相关的 keychain 信息
```

---

Source: [结束脚本 (os.exit)](https://xxtouch.app/docs/handbook/control-flow/os.exit.md)
Path: handbook/control-flow/os.exit.md

# 结束脚本 (os.exit)


## 声明

```lua
os.exit()
```


## 说明

> [`os.exit`](https://cloudwu.github.io/lua53doc/manual.html#pdf-os.exit) 是 Lua 自带的结束进程函数；在 XXTouch 中，它用于结束逻辑上的脚本进程
> 在任意线程中调用都可以结束当前脚本进程，所有线程和监听都会立即终止


## 示例

```lua
os.exit()
```

---

Source: [本机编译 CoreML 模型 (coreml.compile_model)](https://xxtouch.app/docs/handbook/coreml/coreml.compile_model.md)
Path: handbook/coreml/coreml.compile_model.md

# 本机编译 CoreML 模型 (coreml.compile_model)

## 声明

```lua
编译好的模型路径, 错误信息 = coreml.compile_model(模型文件路径)
```

## 参数

- 模型文件路径
    文本型，需要编译的模型路径。iOS 15 及以上支持 `.mlpackage` 格式；iOS 13、14 仅支持旧版 `.mlmodel` 格式

    [YOLO11 转 CoreML 相关文档](https://docs.ultralytics.com/zh/integrations/coreml/)

    <details>

    <summary>macOS 下 YOLO11 格式转换命令参考</summary>

    ```bash
    # 这里假设你已经有 Python 3.10 环境，没有请自行创建（仅在 Python 3.10 下测试通过，更高版本未验证）
    # 先安装 ultralytics，如果已安装则跳过这一步
    pip install ultralytics

    # 在 iOS 13 或 iOS 14 上可以指定 format 为 mlmodel 转换为旧版 mlmodel
    yolo export format=mlmodel nms=True model=best.pt

    # iOS 15 及以上可以指定 format 为 coreml 转换为 mlpackage 模型
    yolo export format=coreml nms=True model=best.pt

    # nms=True 不是必选项
    # 如果你希望把 NMS 内联进导出模型，可以开启它
    # 如果准备在 XXTouch 侧使用 coreml.nms / coreml.rotated_nms 自己做后处理，也可以不带 nms=True
    ```
    </details>

## 返回值

- 编译好的模型路径
    文本型 | nil，编译成功返回编译好的模型路径，编译失败返回 `nil`

- 错误信息
    文本型 | nil，编译成功返回 `nil`，失败时返回错误信息

## 说明

- **软件版本在 1.3.8 或以上方可使用**
- 不支持 iOS 12 以下版本系统
- 这个函数用于将 `.mlpackage` 或 `.mlmodel` 格式的模型编译成设备可直接加载的 `.mlmodelc` 格式
- 不同型号或系统版本的设备上编译的 `.mlmodelc` 不一定可以通用
    <details>

    <summary>NVIDIA 显卡电脑上的 YOLO11 模型训练命令</summary>

    ```bash
    # 先在电脑上安装 Visual Studio 的 C++ 桌面开发套件，如果已安装则跳过这一步，以下是链接
    # https://visualstudio.microsoft.com/
    # 在电脑上下载安装 CUDA 11.8 Toolkit，如果已安装则跳过这一步，以下是链接
    # https://developer.nvidia.com/cuda-11-8-0-download-archive

    # 这里假设你已经有 Python 3.10 环境，没有请自行创建（仅在 Python 3.10 下测试通过，更高版本未验证）
    # 先安装 ultralytics，如果已安装则跳过这一步
    pip install ultralytics

    # 重新安装支持 NVIDIA CUDA 11.8 Toolkit 的 torch 库
    # 如果确认安装过了支持 CUDA 的 torch 库则跳过这一步
    pip uninstall torch torchvision torchaudio  # 卸载电脑上已安装的 CPU 版 torch
    pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu118

    yolo train model=yolo11m.pt data=COCO.yml epochs=300 imgsz=640 device=0  # 使用 GPU0 进行训练
    ```
    </details>

    <details>

    <summary>macOS 上的 YOLO11 模型训练命令</summary>

    ```bash
    # 这里假设你已经有 Python 3.10 环境，没有请自行创建（仅在 Python 3.10 下测试通过，更高版本未验证）
    # 先安装 ultralytics，如果已安装则跳过这一步
    pip install ultralytics

    # 如果已安装 torch 则跳过这一步
    pip install torch torchvision torchaudio

    yolo train model=yolo11m.pt data=COCO.yml epochs=300 imgsz=640 device=mps  # 使用 Metal 着色器加速训练
    ```
    </details>


## 示例

```lua
compiled_model_path = XXT_HOME_PATH..'/models/yolo11m.mlmodelc' -- 编译好的模型存放位置

file.remove(compiled_model_path) -- 测试阶段每次重新编译，模型稳定后可注释掉此行

if not file.exists(compiled_model_path) then -- 如果还没有编译好的模型，则编译一份
    local tmp_path, err = coreml.compile_model(XXT_HOME_PATH..'/models/yolo11m.mlpackage') -- 编译模型
    if not tmp_path then
        error(err)
    end
    file.move(tmp_path, compiled_model_path, 'mo') -- 将编译好的模型移动到指定位置
end
```

---

Source: [打印内容到缓冲区 (print)](https://xxtouch.app/docs/handbook/develop-helper/print.md)
Path: handbook/develop-helper/print.md

# 打印内容到缓冲区 (print)


## 声明

```lua
print([ 参数1, 参数2, ... ])
```


## 参数

- 参数 1, 参数 2, ...
    任意类型，可选参数，可变参数，将会转换成文本输出到缓冲区，参数之间用 `"\t"` 隔开


## 说明

> [`print`](https://cloudwu.github.io/lua53doc/manual.html#pdf-print) 是 Lua 自带的打印输出函数；在 XXTouch 中，它会将内容写入打印缓冲区


## 示例

```lua
print("hello world")
```

---

Source: [重置自动锁屏倒计时 (device.reset_idle)](https://xxtouch.app/docs/handbook/device/device.reset_idle.md)
Path: handbook/device/device.reset_idle.md

# 重置自动锁屏倒计时 (device.reset_idle)


## 声明

```lua
device.reset_idle()
```


## 说明

> 重置自动锁屏倒计时 (使屏幕常亮)
> 不推荐太高频率使用该函数，太高频率（每秒超过 10 次）使用该函数可能导致服务崩溃或系统崩溃


## 示例

```lua
-- 派发一个每 29 秒重置 IDLE 倒计时的任务
thread.dispatch(function()
    while 1 do
        device.reset_idle()
        sys.msleep(29 * 1000)
    end
end)
```
**注**：上述代码中使用了非本章函数及方法 [`thread.dispatch`](/docs/handbook/thread/thread.dispatch.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [! 建立一个对话框对象 (dialog)](https://xxtouch.app/docs/handbook/dialog/new.md)
Path: handbook/dialog/new.md

# ! 建立一个对话框对象 (dialog)


## 声明

```lua
对话框对象 = dialog()
```


## 返回值

- 对话框对象
    对话框，返回一个新建的对话框对象


## 说明

> 建立一个对话框对象
> **注意：** 该函数不接受参数。带参数调用会弹出一个弹窗，声明如下
```lua
dialog(弹窗内容:文本型, 超时秒:实数型)
```
> 例如
```lua
dialog('Hello, XXTouch!', 10)
```


## 示例

```lua
dialog():show()
```


## 完整示例

参考本章结尾 [`:show`](/docs/handbook/dialog/dialogm_show.md) 的完整示例

---

Source: [深拷贝一个表 (table.deep_copy)](https://xxtouch.app/docs/handbook/ext-table/table.deep_copy.md)
Path: handbook/ext-table/table.deep_copy.md

# 深拷贝一个表 (table.deep_copy)


## 声明

```lua
被复制的表 = table.deep_copy(一个表)
```


## 参数

- 一个表
    表型，需要拷贝的表

## 返回值

- 被复制的表
    表型，返回原表的深拷贝副本


## 说明

> 递归地拷贝整个表结构；表中除 function 和 userdata 外的所有值都会被拷贝
> 原表内如存在循环引用，副本中也会保留相同的引用关系


## 示例

```lua
local _g = table.deep_copy(_G)
```

---

Source: [判断一个文件或目录是否存在 (file.exists)](https://xxtouch.app/docs/handbook/file/file.exists.md)
Path: handbook/file/file.exists.md

# 判断一个文件或目录是否存在 (file.exists)


## 声明

```lua
存在信息 = file.exists(文件路径)
```


## 参数

- 文件路径
    文本型，文件或目录绝对路径

## 返回值

- 存在信息
    返回 false 表示路径不存在
    返回 "file" 表示路径是一个文件
    返回 "directory" 表示路径是一个目录


## 说明

> 用于判断一个路径是文件还是目录还是不存在


## 示例

```lua
if file.exists("/var/mobile/1.zip") then
    sys.alert("`/var/mobile/1.zip` 存在")
else
    sys.alert("`/var/mobile/1.zip` 不存在")
end
--
if file.exists("/var/mobile/1.zip")=="file" then
    sys.alert("`/var/mobile/1.zip` 存在并且是个文件")
else
    sys.alert("`/var/mobile/1.zip` 不是文件")
end
--
if file.exists("/var/mobile/123/")=="directory" then
    sys.alert("`/var/mobile/123/` 存在并且是个目录")
else
    sys.alert("`/var/mobile/123/` 不是目录")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [FTP 文件下载 (ftp.download)](https://xxtouch.app/docs/handbook/ftp/ftp.download.md)
Path: handbook/ftp/ftp.download.md

# FTP 文件下载 (ftp.download)


## 声明

```lua
下载成败, 下载信息 = ftp.download(URL, 本地文件路径 [, 连接超时秒, 断点续传模式, 分块回调函数, 缓冲区尺寸 ])
```


## 参数

- URL
    文本型，远端文件地址，账号及密码被包含在这一参数中
- 本地文件路径
    文本型，需要保存到的本地路径
- 连接超时秒
    实数型，可选参数，连接超时时间，单位秒，默认 10
- 断点续传模式
    布尔型，可选参数，是否需要支持断点续传，是为 true，否为 false，默认 false
- 分块回调函数
    函数型，可选参数，分块回调函数，每下载完一个分块都会回调一次该函数，默认 空函数
    分块回调函数第一个参数为当前下载的信息，回调函数返回 true 则打断这次下载
- 缓冲区尺寸
    整数型，可选参数，缓冲区大小字节数，默认自动最优配置

## 返回值

- 下载成败
    布尔型，连接是否成功
- 下载信息
    表型 或 文本型，如果连接成功则返回表型下载信息，否则返回连接失败原因文本描述


## 说明

```lua
-- 第二个返回值下载信息结构如下
{
    resource_size = 远端资源总字节数,
    start_pos = 本次下载从资源的开始的位置,
    size_download = 本次下载的字节数,
    speed_download = 本次下载的速度 (单位：字节/秒) ,
}
```
> 该函数适合大文件下载，在传输的过程中停止脚本可能会缓慢
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 简单示例

> 账号密码写在 URL 中，具体 URL 格式如下 \(中括号内是可选参数\)
```lua
ftp://[账号:密码@]地址[:端口]/路径
```
> 账号或密码中包含 `@`、`:`、`/` 这三个字符可分别用 `%40`、`%3A`、`%2F` 转义（其他在 URL 中非法的字符可使用 URL 百分号编码）
> 例如账号 `havonz`、密码 `11@@22`，示例如下：
```lua
local done, info = ftp.download("ftp://havonz:11%40%4022@192.168.31.13/1.zip", "/var/mobile/1.zip")
if (done) then
    sys.alert("下载完成")
else
    sys.alert("连接失败："..info)
end
```


## 复杂示例

```lua
local done, info = ftp.download("ftp://havonz:123456@192.168.31.13/1.zip", "/var/mobile/1.zip", 10, true, function(binfo)
    local percent = math.floor(((binfo.start_pos + binfo.size_download) / binfo.resource_size) * 100)
    sys.toast("下载进度 "..percent.."%")
end, 4096 * 1024)
--
if (done) then
    if (info.start_pos + info.size_download < info.resource_size) then
        sys.alert(
            "下载中断\n本次下载 "..info.size_download.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始下载"
            .."\n平均速度为 "..math.floor(info.speed_download/1024).." kB/s"
            .."\n还有剩 "..(info.resource_size - (info.start_pos + info.size_download)).." 字节"
        )
    else
        sys.alert(
            "下载完成\n本次下载 "..info.size_download.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始下载"
            .."\n平均速度为 "..math.floor(info.speed_download/1024).." kB/s"
        )
    end
else
    sys.alert("连接失败："..info)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [! 创建硬件游戏手柄 (gamepad.connect)](https://xxtouch.app/docs/handbook/gamepad/gamepad.connect.md)
Path: handbook/gamepad/gamepad.connect.md

# ! 创建硬件游戏手柄 (gamepad.connect)

> **该函数在 20260805 以后版本方可使用**

## 声明

```lua
手柄对象, 错误信息 = gamepad.connect([ 属性 ])
```

## 参数

- 属性
    表型，可选参数，用于设置下列常用设备属性；代码块中的值为省略时的默认值

```lua
{
    VendorID = 0x5858,
    ProductID = 0x0007,
    VersionNumber = 1,
    Product = "XXTouch Gamepad",
    Manufacturer = "XXTouch",
    Transport = "USB",
}
```

还可以设置 `SerialNumber` 和 `LocationID`；其它属性不保证生效。

## 返回值

- 手柄对象
    游戏手柄对象 或 nil，设备创建成功时返回新的手柄对象，失败时返回 nil
- 错误信息
    文本型，设备创建失败时的错误信息

## 说明

- 每次调用都会返回新的独立手柄对象；不同对象的输入状态和生命周期互不影响
- 手柄支持左右摇杆、方向键、数字按键 `1` 至 `32`，以及 `menu` 输入
- 连接等待会让出当前 Lua 执行线程
- 系统不支持该功能时，`gamepad.connect` 返回 `nil, error`
- 连接成功只表示手柄对象已经可以调用；目标 App 是否识别手柄及其全部输入，取决于系统版本和 App 的手柄支持
- `Transport` 只影响本机系统如何识别该手柄。设为 `"Bluetooth"` 或 `"BluetoothLowEnergy"` 不会建立蓝牙连接、广播或配对，也不会让手柄出现在其它设备的蓝牙列表中

## 示例

```lua
local pad, err = gamepad.connect({
    Product = "XXTouch Gamepad",
})
assert(pad, err)

assert(pad:press("a"))
assert(pad:press("menu"))
assert(pad:down("left_shoulder"))
assert(pad:set_stick("left", 0.5, 1))
assert(pad:set_dpad(1, 0))
assert(pad:up("left_shoulder"))
assert(pad:reset())

pad:disconnect()
```

---

Source: [判断一个值是否是图片对象 (image.is)](https://xxtouch.app/docs/handbook/image/image.is.md)
Path: handbook/image/image.is.md

# 判断一个值是否是图片对象 (image.is)


## 声明

```lua
是否图片 = image.is(需要判断的值)
```


## 参数

- 需要判断的值
    值，需要判断是否是图片对象的值

## 返回值

- 是否图片
    布尔型，值是图片对象返回 true，否则返回 false


## 说明

> 判断一个值是否是图片对象


## 示例

```lua
if image.is(img) then
    -- img 是个图片对象
else
    -- img 不是图片对象
end
```

---

Source: [! 模拟按一下物理按键 (key.press)](https://xxtouch.app/docs/handbook/key/key.press.md)
Path: handbook/key/key.press.md

# ! 模拟按一下物理按键 (key.press)

> **本页所述硬件键盘功能在 20260805 以后版本方可使用**

## 声明

```lua
key.press(按键码)
```

## 参数

- 按键码
    文本型，物理按键的按键码，键码在[示例及支持的键码列表](/docs/handbook/key/samples.md)一节查看。

## 说明

> 模拟按下物理按键然后松开它。

- 连接[全局硬件键盘](key.connect_global_keyboard.md)后，普通键盘和数字小键盘按键会通过该对象输入；媒体键和厂商自定义键仍保持原有行为
- 通过 `key(...):press()` 调用时遵循相同规则
- 使用全局硬件键盘时，按键默认保持 10 毫秒，等待期间可能隐式让出；没有全局硬件键盘时，行为与原来一致
- 发送失败时不会自动改用原有输入方式重试

## 示例

参考[本章末尾的综合示例](/docs/handbook/key/samples.md)。

---

Source: [! 创建并连接一个硬件鼠标对象 (mouse.connect)](https://xxtouch.app/docs/handbook/mouse/mouse.connect.md)
Path: handbook/mouse/mouse.connect.md

# ! 创建并连接一个硬件鼠标对象 (mouse.connect)

> **该函数在 20260805 以后版本方可使用**


## 声明

```lua
鼠标对象, 错误信息 = mouse.connect([ 属性 ])
```


## 参数

- 属性
    表型，可选参数，用于设置硬件鼠标属性


## 返回值

- 鼠标对象
    硬件鼠标对象，创建成功时返回；创建失败时返回 `nil`
- 错误信息
    文本型，创建失败的原因


## 说明

> 每次调用都会创建独立的鼠标对象，各对象的按键状态和连接生命周期互不影响。返回成功表示该对象已经可以调用；目标 App 是否响应仍取决于 iOS 和 App。
> **该函数会在等待连接时让出当前 Lua 执行线程。**

`属性` 可省略，以下是常用可配置属性及其默认值：

```lua
{
    VendorID = 0x5858,
    ProductID = 0x0006,
    VersionNumber = 1,
    Product = "XXTouch Mouse",
    Manufacturer = "XXTouch",
    Transport = "USB",
}
```

> 还可以设置 `SerialNumber` 和 `LocationID`；其它属性不保证生效。
> `Transport` 只影响 iOS 或目标 App 识别鼠标的方式。设为 `"BluetoothLowEnergy"` 不会建立蓝牙连接、广播或配对，也不会让鼠标出现在其它设备的蓝牙列表中。
> 任意鼠标操作发送失败时，该对象会自动释放全部按键并断开，不会改用触摸输入重试。


## 示例

```lua
local m, err = mouse.connect({
    Product = "XXTouch Mouse",
})
assert(m, err)

assert(m:move(100, 0))
assert(m:down("left"))
assert(m:move(100, 50))
assert(m:up("left"))
assert(m:click("right", 60))
assert(m:click(13))
assert(m:scroll(0, 10))

m:disconnect()
```

---

Source: [ONNX Runtime 张量模块](https://xxtouch.app/docs/handbook/onnxruntime/onnxruntime.tensor_module.md)
Path: handbook/onnxruntime/onnxruntime.tensor_module.md

# ONNX Runtime 张量模块

> **该模块在 20260402 以后版本方可使用**

本页说明 `onnxruntime` 模块中最常用的 tensor 相关函数和对象方法。

## 创建与转换

### `onnxruntime.tensor(type, shape[, data])`

```lua
张量, 错误信息 = onnxruntime.tensor("float32", {1, 3}, {1, 2, 3})
```

用于创建一个普通 ORT tensor。

- `type` 为元素类型名称
- `shape` 为形状数组
- `data` 可省略；省略时创建空张量
- 数值 tensor 可以传标量，表示用同一个值填满整个张量
- `string` tensor 可以传单个字符串，表示按同一个字符串填满整个张量

### `onnxruntime.tensor_from_bytes(type, shape, bytes)`

```lua
张量, 错误信息 = onnxruntime.tensor_from_bytes("float32", {1, 3}, 原始字节串)
```

用于从连续原始字节创建 tensor。

- 只支持数值和 `bool` 类型
- 字节长度必须与 `shape` 和 `type` 完全匹配

### `onnxruntime.tensor_from_cv_mat(mat[, opts])`

```lua
张量, 错误信息 = onnxruntime.tensor_from_cv_mat(mat, {
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})
```

用于把 `cv.mat` 转成 tensor。

说明：

- 需要先 `require("image.cv")`
- `opts.type` 是目标 tensor 元素类型

### `onnxruntime.tensor_from_quad(mat, quad[, opts])`

```lua
张量, 错误信息 = onnxruntime.tensor_from_quad(mat, {
    {x = 0, y = 0},
    {x = 100, y = 0},
    {x = 100, y = 32},
    {x = 0, y = 32},
}, {
    width = 100,
    height = 32,
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})
```

从 `cv.mat` 中按四边形区域做透视裁剪，并直接得到 ORT tensor。

- 需要先 `require("image.cv")`
- `quad` 可以直接传四个点，也可以传带 `points` 字段的表
- 常用 `opts` 与 `tensor_from_image()` 基本一致，额外常见字段有 `content_width`、`content_height`、`border_type`
- 适合 OCR 识别前的单框拉正与张量化

### `onnxruntime.tensor_from_quads(mat, quads[, opts])`

```lua
批量张量, 错误信息 = onnxruntime.tensor_from_quads(mat, {
    {
        points = quad1,
        content_width = 96,
        content_height = 32,
    },
    {
        points = quad2,
        content_width = 80,
        content_height = 32,
    },
}, {
    width = 96,
    height = 32,
    resize_mode = "top_left_letterbox",
    border_type = "replicate",
})
```

批量裁剪多个四边形并自动拼成 batch tensor。

- 需要先 `require("image.cv")`
- `quads` 必须是非空数组；每项可以带 `points`
- 每项里的 `content_width`、`content_height` 会覆盖全局 `opts` 里的同名字段
- 返回值会按结果 rank 自动走 `stack()` 或 `concat()` 拼成 batch，适合 OCR 多框批处理

### `onnxruntime.tensor_from_image(image[, opts])`

```lua
张量, 预处理信息 = onnxruntime.tensor_from_image(图像对象, {
    width = 224,
    height = 224,
    layout = "nchw",
    channel_order = "rgb",
    data_type = "float32",
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    resize_mode = "letterbox",
})
```

用于把图片对象直接转换成 ONNX Runtime 可用的输入张量。

常用配置字段：

- `width` / `height`
- `layout`：`"nchw"`、`"nhwc"`、`"chw"`、`"hwc"`
- `channel_order`：`"rgb"`、`"bgr"`、`"gray"`、`"grey"`、`"grayscale"`
- `data_type`
- `scale`
- `mean`
- `std`
- `resize_mode`：`"stretch"`、`"letterbox"`、`"center_crop"`
- `letterbox_mode`：支持 `"top_left"`，其余情况按居中补边处理
- `pad_color`
- `interpolation`：`"bilinear"`、`"nearest"`
- `alpha_mode`：`"ignore"`、`"white"`、`"black"`、`"premultiply"`
- `crop = {x, y, width, height}`
- `add_batch`

成功时第二个返回值是预处理信息表，包含：

- `src_width` / `src_height`
- `crop_x` / `crop_y` / `crop_width` / `crop_height`
- `dst_width` / `dst_height`
- `resized_width` / `resized_height`
- `layout`
- `channel_order`
- `resize_mode`
- `scale_x` / `scale_y` / `ratio`
- `offset_x` / `offset_y`
- `pad_left` / `pad_top` / `pad_right` / `pad_bottom`

### `onnxruntime.tensor_from_images(images[, opts])`

```lua
批量张量, 批量元信息 = onnxruntime.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})
```

用于把一组图像批量转换成 tensor。

- 原图尺寸可以不同
- 只要每张图解析后的输出 shape 与 `data_type` 一致，就能拼成 batch
- 第二个返回值是与输入顺序对应的元信息数组

### `onnxruntime.image_from_tensor(tensor[, opts])`

```lua
图像对象, 错误信息 = onnxruntime.image_from_tensor(张量, {
    layout = "nchw",
    channel_order = "rgb",
    batch_index = 1,
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    value_range = "0_1",
})
```

用于把 2D / 3D / 4D tensor 还原成图像对象，适合调试模型输入输出。

常用配置字段：

- `layout`
- `channel_order`
- `batch_index`：1-based，默认第 `1` 个 batch
- `scale`
- `mean`
- `std`
- `clamp`
- `value_range`：`"0_255"` 或 `"0_1"`

说明：

- 仅支持 2D / 3D / 4D tensor
- 通道数仅支持 `1` 或 `3`

## 张量对象方法

### 基础信息

- `tensor:shape()`
- `tensor:rank()`
- `tensor:size()`
- `tensor:type()`
- `tensor:to_table()`
- `tensor:bytes()`

说明：

- `to_table()` 会把内容展开成 Lua 表
- `bytes()` 只支持数值和 `bool` tensor

### 读写与复制

- `tensor:get(index1[, index2, ...])`
- `tensor:set(index1[, index2, ...], value)`
- `tensor:fill(value_or_table)`
- `tensor:clone()`
- `tensor:copy_from_bytes(raw_bytes)`
- `tensor:to(type)`

说明：

- `fill()` 传标量时会填满整个张量，传表时元素数必须完全匹配
- `copy_from_bytes()` 只支持数值和 `bool` tensor，字节长度必须完全匹配
- `get()` / `set()` 的索引语义是 **1-based**
- `tensor:to("string")` 目前只支持 `string -> string`

### 形状与索引

- `tensor:reshape(shape)`
- `tensor:transpose([axes])`
- `tensor:flatten([start_dim[, end_dim]])`
- `tensor:squeeze([dim])`
- `tensor:unsqueeze(dim)`
- `tensor:slice(dim, start, stop[, step])`
- `tensor:select(dim, index)`
- `tensor:gather(dim, indices)`

说明：

- `slice()` 的 `start` 和 `stop` 都是 **1-based 且包含结束位置**
- `slice()` 的 `step` 必须为正整数
- `select()` 会移除被选中的那一维
- `gather()` 的 `indices` 可以是 Lua 数组，也可以是形状 `[N]` 的 tensor；索引语义同样是 **1-based**
- 这几类方法返回的都是新的 tensor 对象

### 数值运算

- `tensor:add(other)`
- `tensor:sub(other)`
- `tensor:mul(other)`
- `tensor:div(other)`
- `tensor:clamp(min, max)`
- `tensor:sigmoid()`
- `tensor:exp()`
- `tensor:matmul(other)`
- `tensor:dot(other)`

说明：

- `other` 可以是标量，也可以是形状一致的 tensor
- `matmul()` 当前支持 rank-1 / rank-2 tensor 组合
- `sigmoid()` / `exp()` / `matmul()` 的返回值会提升到浮点结果类型
- 以上运算都不支持 `string` tensor

### 归约、排序与概率

- `tensor:argmax([axis])`
- `tensor:sum([axis])`
- `tensor:mean([axis])`
- `tensor:max([axis])`
- `tensor:min([axis])`
- `tensor:softmax([axis])`
- `tensor:normalize([axis])`
- `tensor:sort([axis[, descending]])`
- `tensor:topk(k[, axis])`

说明：

- `argmax()` 不传轴时返回单个 **1-based** 索引
- `argmax(axis)` 返回 `int64` tensor，索引语义也是 **1-based**
- `sort()` 返回 `{ values = 张量, indices = 张量 }`
- `topk()` 返回 `{ values = 张量, indices = 张量 }`
- `sort()` / `topk()` 返回的索引都是 **1-based**

### OpenCV 桥接

- `tensor:to_cv_mat([opts])`

```lua
mat, 错误信息 = tensor:to_cv_mat({
    layout = "hwc",
    channel_order = "rgb",
    coreml_data_type = "uint8",
})
```

说明：

- 需要先 `require("image.cv")`
- 某些 tensor 类型不能直接映射到 `cv.mat`，这种情况需要显式传 `coreml_data_type`

## 模块级张量辅助

### 基础数值辅助

- `onnxruntime.clamp(tensor, min, max)`
- `onnxruntime.sigmoid(tensor)`
- `onnxruntime.exp(tensor)`
- `onnxruntime.where(condition, x, y)`
- `onnxruntime.matmul(lhs, rhs)`
- `onnxruntime.concat(tensors[, axis])`
- `onnxruntime.stack(tensors[, axis])`

说明：

- `clamp()`、`sigmoid()`、`exp()`、`matmul()` 与对应的 `tensor:` 方法共享同一套实现
- `where()` 支持标量 / 布尔值 / tensor 混用，并按广播规则计算结果

### 额外后处理辅助

- `onnxruntime.mask_iou(lhs_mask, rhs_mask)`
- `onnxruntime.db_postprocess(score_map[, opts])`

说明：

- `mask_iou()` 用于直接计算两张 mask 的交并比
- `mask_iou()` 还支持第三个参数 `opts`，可传 `compare_size = true`，或显式传 `width` / `height` 作为对齐后的比较尺寸
- `db_postprocess()` 适合 DB / DBNet 一类文本检测后处理；输入支持 `[H, W]`、`[C, H, W]` 或 `[N, C, H, W]`
- `db_postprocess()` 返回检测数组，每项都带 `score`、`points` 和 `box`；`meta` / `image_meta` 可直接复用图像张量化返回的元信息

### `onnxruntime.nms(boxes, scores[, opts])`

普通矩形框 NMS。

常用选项：

- `iou_threshold`
- `score_threshold`
- `top_k`
- `class_aware`
- `class_ids`

返回值是 `int64` tensor，索引为 **1-based**。

### `onnxruntime.box_points(rotated_boxes)`

把旋转框 `[cx, cy, w, h, theta]` 转成四个顶点坐标。

- 输入可以是形状 `[5]`、`[1, 5]` 或 `[N, 5]` 的 tensor
- 单个框返回一个 Lua 点表；多个框返回点表数组

### `onnxruntime.xywh_to_xyxy(boxes)`

把矩形框从 `[cx, cy, w, h]` 转成 `[x1, y1, x2, y2]`。

### `onnxruntime.xyxy_to_xywh(boxes)`

把矩形框从 `[x1, y1, x2, y2]` 转成 `[cx, cy, w, h]`。

### `onnxruntime.rotated_iou(box1, box2)`

计算两个旋转框的 IoU。

### `onnxruntime.rotated_nms(boxes, scores[, opts])`

旋转框 NMS。返回值同样是 `int64` tensor，索引为 **1-based**。

- `boxes` 必须是 `[N, 5]` 的旋转框 tensor
- `scores` 可以是 Lua 数组，也可以是形状 `[N]` / `[N, 1]` 的 tensor

### `onnxruntime.create_decoder(schema)`

创建一个可复用 decoder 对象。

- decoder 对象支持 `:decode(output[, opts])`、`:task()`、`:schema()`
- 适合把检测 / OBB / 分类输出的 schema 先固化，再多次复用

### `onnxruntime.decode_yolo(output[, opts])`

直接按内置 YOLO 检测逻辑解码，返回 detection record 列表。

### `onnxruntime.decode_yolo_obb(output[, opts])`

直接按内置 YOLO OBB 逻辑解码，返回旋转框 detection record 列表。

### `onnxruntime.decode_matrix_candidates(output, schema[, opts])`

按 schema 把矩阵输出拆成候选张量表，返回字段通常包括：

- `boxes`
- `scores`
- `class_ids`
- `keep_indices`
- `selected_rows`
- `angles`（仅 OBB 等相关 schema）

### `onnxruntime.decode_dense_detection(output, opts)`

把 dense detection head 输出解码成：

- `boxes`
- `scores`
- `labels`

其中 `boxes` / `scores` / `labels` 都是 tensor。

- 输入支持 `[R, C]` 或 `[N, R, C]`
- `opts.strides` 是必填项，且必须是非空正整数数组
- `decode_width`、`decode_height` 也是必填项
- 当前只支持 `box_encoding = "grid_center_log_wh"`
- 其余常用字段包括 `box_offset`、`score_offset`、`class_offset`、`num_classes`、`score_threshold`
- 当传入 batched 输出时，返回值是按 batch 组织的 Lua 数组

### `onnxruntime.records_from_boxes(boxes, scores, class_ids[, keep_indices])`

把 `[N, 4]` 框、分数、类别等 tensor 整理成 Lua record 列表，每项通常会带：

- `box`
- `score`
- `class_id`
- `row_index`
- `x1` / `y1` / `x2` / `y2`
- `width` / `height`
- `cx` / `cy`

### `onnxruntime.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])`

把 OBB 行数据整理成 Lua record 列表。

- `opts` 支持 `x_index`、`y_index`、`width_index`、`height_index`

### `onnxruntime.points_to_records(points[, opts])`

把 `[N, P, D]` 或 `[N, P*D]` 的点 / 关键点 tensor 整理成 Lua table。

- `opts` 支持 `point_count` / `keypoint_count`
- `opts` 支持 `point_dim` / `keypoint_dim`

### 掩码辅助

#### `onnxruntime.threshold_masks(masks, threshold)`

把连续 mask tensor 阈值化为 Lua mask table 列表。每个 mask 会包含：

- `width`
- `height`
- `bits`
- `pixel_count`
- `bounds`

#### `onnxruntime.crop_masks_by_boxes(masks, boxes)`

按 `[N, 4]` 框裁剪阈值化后的 mask 列表。

#### `onnxruntime.resize_masks(masks, width, height[, opts])`

把 mask 列表缩放到指定尺寸。

- 当前仅支持 `opts.interpolation = "nearest"`

#### `onnxruntime.mask_to_polygon(mask[, opts])`

把单个二值 mask 转为多边形点列。

- `opts.epsilon` / `opts.approx_epsilon` 可用于近似简化

#### `onnxruntime.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])`

把原型 mask、mask 系数和检测框投影回目标图像尺寸。

- `project_masks()` 是它的别名
- 返回值是 Lua mask table 列表，而不是 tensor

### 关键点与几何辅助

- `onnxruntime.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])`
- `onnxruntime.scale_boxes(boxes, transform)`
- `onnxruntime.clip_boxes(boxes, clip_width, clip_height)`
- `onnxruntime.scale_points(points, transform[, opts])`
- `onnxruntime.scale_keypoints(points, transform[, opts])`
- `onnxruntime.clip_keypoints(points, clip_width, clip_height[, opts])`

说明：

- `reshape_keypoints()` 支持 `[N, K*D]` 与 `[N, K, D]` 之间整理
- `scale_points()` 默认按普通点布局解析；`scale_keypoints()` 默认按关键点布局解析
- `transform` 相关 table 与图像预处理元信息字段对齐，常见字段包括 `scale_x`、`scale_y`、`pad_left`、`pad_top`

### `onnxruntime.tracker([opts])`

创建一个可复用的跟踪器对象，支持：

- `tracker:update(detections[, timestamp])`
- `tracker:reset()`
- `tracker:state()`
- `tracker:close()`

常用配置字段：

- `iou_threshold`
- `max_age`
- `min_hits`

### `onnxruntime.ctc_greedy_decode(logits[, opts])`

返回形如：

- `indices`
- `text`
- `confidence`

- 输入支持 `[T, C]` 或 `[N, T, C]`
- 支持 `blank_index`、`merge_repeated`、`apply_softmax`、`return_probabilities`、`charset`
- 一定返回 `indices`
- 只有传了 `charset` 才会带 `text`
- 只有启用 `apply_softmax` 或 `return_probabilities` 才会带 `confidence`
- 只有启用 `return_probabilities` 才会额外带 `probabilities` 和 `probability_confidence`
- 当输入为 batch 时，返回 batch result 数组

### `onnxruntime.sample_logits(logits[, opts])`

支持以下采样参数：

- `argmax`
- `temperature`
- `top_k`
- `top_p`
- `min_p`
- `seed`

1D logits 返回单个索引；多行 logits 返回 `int64` tensor，索引语义为 **1-based**。

## 示例

```lua
local ort = require("onnxruntime")

local tensor = assert(ort.tensor("float32", {2, 3}, {
    1, 9, 3,
    8, 2, 7,
}))

local sliced = assert(tensor:slice(2, 2, 3))
print(sliced:to_table()[1]) -- 9

local topk = assert(tensor:topk(2, 2))
print(topk.values:to_table()[1])  -- 9
print(topk.indices:to_table()[1]) -- 2
```

---

Source: [LuaCJSON 扩展库](https://xxtouch.app/docs/handbook/open-source/luacjson.md)
Path: handbook/open-source/luacjson.md

# LuaCJSON 扩展库

[LuaCJSON 手册地址](https://kyne.au/~mark/software/lua-cjson-manual.html)

**注：** XXTouch 内置的 JSON 模块就是 LuaCJSON，参考 [JSON 模块 (json)](/docs/handbook/json/index.md)

---

---

Source: [写内容进剪贴板 (pasteboard.write)](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.write.md)
Path: handbook/pasteboard/pasteboard.write.md

# 写内容进剪贴板 (pasteboard.write)


## 声明

```lua
pasteboard.write(数据 [, 通用类型标识 ])
pasteboard.write(剪贴板项目 [, 选项 ])
pasteboard.write(剪贴板项目列表 [, 选项 ])
```


## 参数

- 数据
    字符串型，需要写入到剪贴板的内容
    表型，剪贴板项目，键为 **通用类型标识**，值为字符串型数据（自 20260428 版本起支持）
    表型，剪贴板项目列表，每项均为剪贴板项目（自 20260428 版本起支持）
- 通用类型标识
    文本型，可选参数，[Uniform Type Identifiers](https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html)，默认 "public.utf8-plain-text"
- 选项
    表型，可选参数（自 20260428 版本起支持）
    `local_only` 布尔型，仅保存在本机，iOS 10 及以上支持
    `expiration_date` 数字型，Unix 时间戳，单位秒，iOS 10 及以上支持

    <details>

    <summary>剪贴板项目结构</summary>

    ```lua
    {
        ["public.utf8-plain-text"] = "普通文本",
        ["public.rtf"] = "RTF 数据",
        ["public.html"] = "HTML 数据",
        ["public.png"] = "PNG 二进制数据",
        ...
    }
    ```

    </details>


## 返回值

- 是否成功
    布尔型，写入成功返回 `true`，否则返回 `false`

## 说明

> 写内容进系统剪贴板
> 关键词：写入剪贴板、写入剪切板、写入粘贴板
> 传入剪贴板项目或剪贴板项目列表时，会向同一个剪贴板项目写入多种格式表示。iOS 9 会忽略 **选项** 参数。

## 示例

```lua
pasteboard.write("hello") -- 将文本 "hello" 写入到剪贴板中
--
pasteboard.write(screen.image():png_data(), 'public.png') -- 将当前屏幕截图写入到剪贴板
--
pasteboard.write([[{\rtf1\ansi\deff0
{\fonttbl{\f0 Helvetica;}}
{\colortbl;\red255\green0\blue0;}
\f0\fs32 normal {\b bold} {\i italic} \cf1 red\cf0\par
\u20320?\u22909?
}]], "public.rtf") -- 将 RTF 富文本写入到剪贴板中

-- 20260428 以上版本支持向同一个剪贴板项目写入多种格式
pasteboard.write({
    ["public.utf8-plain-text"] = "normal bold italic red\n你好",
    ["public.rtf"] = [[{\rtf1\ansi\deff0
{\fonttbl{\f0 Helvetica;}}
{\colortbl;\red255\green0\blue0;}
\f0\fs32 normal {\b bold} {\i italic} \cf1 red\cf0\par
\u20320?\u22909?
}]],
    ["public.html"] = [[<p>normal <b>bold</b> <i>italic</i> <span style="color:red">red</span><br>你好</p>]],
}, {
    local_only = true,
    expiration_date = os.time() + 3600,
})
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)

---

Source: [读取属性表文件 (plist.read)](https://xxtouch.app/docs/handbook/plist/plist.read.md)
Path: handbook/plist/plist.read.md

# 读取属性表文件 (plist.read)


## 声明

```lua
关联表 = plist.read(文件路径)
```


## 参数

- 文件路径
    文本型，需要读取的 plist 文件的绝对路径

## 返回值

- 关联表
    表型 或 nil，读取成功则返回 plist 的树形结构对应的一个表，否则返回 nil


## 说明

> 读取 plist 文件转换成表
> plist 文件中的非通用数据类型值不支持读取，会被忽略
> 该函数可在 XUI 中使用


## 示例

```lua
local plist = require("plist")
local plfilename = "/var/mobile/Library/Caches/com.apple.mobile.installation.plist" --设置plist路径
local tmp2 = plist.read(plfilename)                 --读取plist文件内容并返回一个TABLE
sys.alert(tmp2['Metadata']['ProductBuildVersion'])  --显示ProductBuildVersion的键值
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [存储值到进程字典 (proc_put)](https://xxtouch.app/docs/handbook/proc/proc_put.md)
Path: handbook/proc/proc_put.md

# 存储值到进程字典 (proc_put)


## 声明

```lua
旧值 = proc_put(键, 新值)
```


## 参数

- 键
    字符串型
- 新值
    字符串型，代表需要设置的值

## 返回值

- 旧值
    字符串型，返回这个键位置的旧的值，如果没有则返回空字符串


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程词典全部被保留**
> 存储值到进程字典并返回该键位置原来的值
> 如果该键位置原先没有值，则返回空字符串
> 存储空字符串代表清空该键位置


## 示例

```lua
local bill = ""
while bill == "" do
    bill = proc_put("billno", "")
end
print("billno: ".. bill)
```

---

Source: [初始化旋转坐标系 (screen.init)](https://xxtouch.app/docs/handbook/screen/screen.init.md)
Path: handbook/screen/screen.init.md

# 初始化旋转坐标系 (screen.init)


## 声明

```lua
原坐标系 = screen.init(坐标系)
```


## 参数

- 坐标系
    整数型
    0 表示竖屏 home 在下
    1 表示横屏 home 在右
    2 表示横屏 home 在左
    3 表示竖屏 home 在上

## 返回值

- 原坐标系
    整数型，返回这个函数调用之前使用的坐标系


## 说明

> 初始化取色或点击的坐标系，会影响以下函数坐标参数及返回值的含义：
```
screen.get_color
screen.is_colors
screen.find_color
screen.ocr_text
screen.image
touch.on
touch.move
touch.off
touch.tap
```

以 iPhone 8 为例 (750x1334 分辨率)：

<details>

<summary>默认竖屏坐标系是这样的 screen.init(0)</summary>

```
(0,0) 物理左上角
┌──────────────────────────────────▶ x+
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│
│                                  │
│                                  │
▼ y+                               ▼
                                (750,1334) 物理右下角
┌──────────────────────────────────┐
│               Home               │
└──────────────────────────────────┘
```
</details>


<details>

<summary>横屏 Home 在右是这样的 screen.init(1)</summary>

```
 (0,0)
   ┌────────────────────────────────────────────────▶ x+ 物理右下角
   │                                                 │   ┌───┐
   │                                                     │   │
   │                                                 │   │   │
   │                                                     │   │
   │                                                 │   │   │
   │                                                     │ H │
   │                                                 │   │ o │
   │                                                     │ m │
   │                                                 │   │ e │
   │                                                     │   │
   │                                                 │   │   │
   │                                                     │   │
   │                                                 │   │   │
   │                                                 │   └───┘
   ▼ y+                                              ▼
物理左上角                                        (1334,750)
```
</details>


<details>

<summary>横屏 Home 在左是这样的 screen.init(2)</summary>

```
      (0,0)
        ┌────────────────────────────────────────────────▶ x+ 物理左上角
┌───┐   │                                                 │
│   │   │
│   │   │                                                 │
│   │   │
│   │   │                                                 │
│ H │   │
│ o │   │                                                 │
│ m │   │
│ e │   │                                                 │
│   │   │
│   │   │                                                 │
│   │   │
│   │   │                                                 │
└───┘   │                                                 │
        ▼ y+                                              ▼
     物理右下角                                        (1334,750)
```
</details>


<details>

<summary>竖屏 Home 在上是这样的 screen.init(3)</summary>

```
   ┌──────────────────────────────────┐
   │               Home               │
   └──────────────────────────────────┘
 (0,0) 物理右下角
   ┌──────────────────────────────────▶ x+
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │
   │                                  │
   │                                  │
   ▼ y+                               ▼
                                  (750,1334) 物理左上角
```
</details>


## 示例

```lua
screen.init(0)    -- home 在下
screen.init(1)    -- home 在右
screen.init(2)    -- home 在左
screen.init(3)    -- home 在上
```

使用以下别名调用也可以实现相同效果
```lua
screen.init_home_on_bottom()    -- home 在下
screen.init_home_on_right()     -- home 在右
screen.init_home_on_left()      -- home 在左
screen.init_home_on_top()       -- home 在上
```

---

Source: [开发及周边工具下载](https://xxtouch.app/docs/handbook/supplement/dev-tools.md)
Path: handbook/supplement/dev-tools.md

# 开发及周边工具下载

> - [在 VSCode 中安装 XXTouch 脚本开发助手](vscode:extension/xxtouch.xxtouch)
>     - VSCode 从这里下载：https://code.visualstudio.com/
> - [在 Cursor 中安装 XXTouch 脚本开发助手](cursor:extension/xxtouch.xxtouch)
>     - Cursor 从这里下载：https://cursor.sh/
> - [在 Devin 中安装 XXTouch 脚本开发助手](devin:extension/xxtouch.xxtouch)
>     - Devin 从这里下载：https://devin.ai/desktop
> - [在 Qoder 中安装 XXTouch 脚本开发助手](qoder:extension/xxtouch.xxtouch)
>     - Qoder 从这里下载：https://qoder.com/ide
> - [在 TRAE 中安装 XXTouch 脚本开发助手](trae:extension/xxtouch.xxtouch)
>     - TRAE 从这里下载：https://trae.ai/ide
> - [下载 XXTouch 脚本开发助手 .vsix](https://marketplace.visualstudio.com/_apis/public/gallery/publishers/xxtouch/vsextensions/xxtouch/latest/vspackage)


---

> - [XXT 局域网中控](https://xxtlc-releases.xxtouch.app/) (包含 MCP 和 Skills 以及集成一个轻量开发环境)

---

> - [XXT 云控制器](https://xxtccc-releases.xxtouch.app/) (开源自部署)


## 旧版工具

> - [XXT 取色器 Windows 版](http://xxt-dist.xxtouch.app/XXTColorPicker/XXTColorPicker%201.0.36%20For%20Windows.7z)
> - [XXT 取色器 macOS 版](http://xxt-dist.xxtouch.app/XXTColorPicker/XXTColorPicker%201.0.36%20For%20macOS%20(depends%20JRE).zip)

---

> - [XXT 编辑器 Windows 版](http://xxt-dist.xxtouch.app/XXTStudio/XXTStudio-Win-2026091115.zip)
> - [XXT 编辑器 macOS 版](http://xxt-dist.xxtouch.app/XXTStudio/XXTStudio-macOS-2026091115.zip)

---

Source: [显示提示文字 (sys.toast)](https://xxtouch.app/docs/handbook/sys/sys.toast.md)
Path: handbook/sys/sys.toast.md

# 显示提示文字 (sys.toast)


## 声明

```lua
sys.toast(文字内容 [, 旋转方向 ])
```


## 参数

- 文字内容
    文本型，代表需要显示的文字
- 旋转方向
    整数型，屏幕旋转方向，可选参数，默认为最后一次调用 [`screen.init`](/docs/handbook/screen/screen.init.md) 所设的那个方向
    `0` 表示竖屏 home 在下
    `1` 表示横屏 home 在右
    `2` 表示横屏 home 在左
    `3` 表示竖屏 home 在上
    `-1` 表示立刻隐藏 toast


## 说明

> 在当前旋转坐标系的屏幕下方显示提示文字
> **该函数是异步进行的，提示文字总计显示时间为 2.8 秒，不会拦截点击**
> **iOS 13.2+ 不影响取色**


## 示例

```lua
-- 显示一个 toast
sys.toast("Hello World")
```

## 示例

```lua
-- 实时显示当前日期时间
while (true) do
    sys.toast("默认长按音量键可停止脚本\n\n"..os.date("%Y年%m月%d日%H点%M分%S秒"), device.front_orien())
    sys.msleep(1000)
end
```
**注**：上述代码中使用了非本章函数 [`device.front_orien`](/docs/handbook/device/device.front_orien.md)、[`os.date`](/docs/handbook/supplement/os.date.md)

---

Source: [电话呼入呼出回调消息](https://xxtouch.app/docs/handbook/system-callback/call.md)
Path: handbook/system-callback/call.md

# 电话呼入呼出回调消息


## 声明

```lua
thread.register_event("xxtouch.call_callback", function(val)
    if (val == "in") then
        -- 有电话呼入
    elseif (val == "out") then
        -- 有电话呼出
    elseif (val == "disconnected") then
        -- 电话被挂断
    end
end)
```


## 状态

- in
    - 来电呼入时，以 xxtouch.call_callback 标识的进程队列词典会推入该值
- out
    - 呼出电话时，以 xxtouch.call_callback 标识的进程队列词典会推入该值
- disconnected
    - 来电或去电挂断时，以 xxtouch.call_callback 标识的进程队列词典会推入该值


## 说明

> 收到系统电话呼入或呼出消息时，该消息标识的进程队列词典会推入一个状态


## 示例

```lua
-- 清空消息队列
proc_queue_clear("xxtouch.call_callback")
--
sys.toast("脚本从现在开始监听来电事件，二十秒后取消监听")
--
-- 开始建立监听回调
local eid = thread.register_event("xxtouch.call_callback", function(val)
    if (val == "in") then
        sys.toast("来电话了")
    elseif (val == "out") then
        sys.toast("正在打电话出去")
    elseif (val == "disconnected") then
        sys.toast("电话挂断了")
    end
end)
--
sys.msleep(20000) -- 等待 20 秒
--
-- 反注册回调函数，如果不反注册监听，那么脚本不会在此结束
thread.unregister_event("xxtouch.call_callback", eid)
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`proc_queue_clear`](/docs/handbook/proc/proc_queue_clear.md)、[`thread.register_event`](/docs/handbook/thread/thread.register_event.md)、[`thread.unregister_event`](/docs/handbook/thread/thread.unregister_event.md)

---

Source: [派发一个任务 (thread.dispatch)](https://xxtouch.app/docs/handbook/thread/thread.dispatch.md)
Path: handbook/thread/thread.dispatch.md

# 派发一个任务 (thread.dispatch)


## 声明

```lua
任务ID = thread.dispatch(任务 [, 错误回调 ])
```


## 参数

- 任务
    函数型，这个函数将加入任务队列
- 错误回调
    函数型，当执行任务时发生异常，则会回调这个函数并不再抛出，可选参数，默认在异常时抛出错误

## 返回值

- 任务 ID
    整数型


## 说明

> 派发一个任务到队列，当调度器空闲时开始执行该任务


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [! 模拟手指轻触一次屏幕 (touch.tap)](https://xxtouch.app/docs/handbook/touch/touch.tap.md)
Path: handbook/touch/touch.tap.md

# ! 模拟手指轻触一次屏幕 (touch.tap)


## 声明

```lua
touch.tap(横坐标, 纵坐标 [, 延迟毫秒, 操作后等待毫秒 ])
```

## 参数

- 横坐标, 纵坐标
    整数型，需要轻触的点于当前旋转坐标系的坐标
- 延迟毫秒
    整数型，可选参数，接触屏幕到离开屏幕之间的间隔时间，单位毫秒，默认 30
- 操作后等待毫秒
    整数型，可选参数，轻触完成之后的等待时间，单位毫秒，默认 0


## 说明

> 模拟手指轻触一次屏幕指定位置
> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**
> **注:** 该方法在调用完成之前会自动分配并占用一个手指 id，手指 id 的数量是有限的 (大约 30 个) ，超出限制再调用 [touch.on](/docs/handbook/touch/touch.on.md) 或 [touch.tap](/docs/handbook/touch/touch.tap.md) 会抛出 `finger pool overflow` 错误，注意不要**同时占用**过多手指 id，及时调用 :off 方法释放手指


## 示例

```lua
touch.tap(100, 100) -- 点一下屏幕上 100, 100 这个位置

touch.tap(100, 100, 300) -- 在屏幕上的 100, 100 这个位置按下，等待 0.3 秒再抬起

touch.tap(100, 100, 300, 1000) -- 在屏幕上的 100, 100 这个位置按下，等待 0.3 秒再抬起，再等待 1 秒
```

---

Source: [选择器字段说明](https://xxtouch.app/docs/handbook/ui_element/selector.md)
Path: handbook/ui_element/selector.md

# 选择器字段说明

> **该模块在 20260507 以后版本方可使用**

选择器是一个 Lua 表，用于描述要查找或操作的 UI 元素。建议优先使用可读文本和角色组合定位，必要时再加 `index` 区分同名元素。

## 示例

```lua
local selector = {
    title = "搜索",
    role = "text_field",
}

local item = ui_element.find(selector)
```

## 字段

- title / text
    文本型，匹配元素的可读标题。两者含义相同。
- text_contains
    文本型，匹配可读标题中包含的子串。
- value
    文本型、数值型或布尔型，匹配元素当前值。
- value_contains
    文本型，匹配元素值中包含的子串。
- identifier
    文本型，匹配元素标识符。并非所有 App 都会提供。
- bundle_id
    文本型，匹配元素所属 App 的 bundle identifier。
- role
    文本型，匹配元素类型。常用值包括 `button`、`text_field`、`static_text`、`switch`、`checkbox`、`radio`、`slider`、`picker`、`scrollable`、`link`、`image`、`keyboard_key`。
- traits
    文本型或文本数组，匹配元素特征名称，例如 `Button`、`StaticText`、`Toggle`、`Adjustable`。
- visible
    布尔型，匹配元素是否可见。
- hittable
    布尔型，匹配元素当前是否可被命中。动作类接口通常需要目标可命中。
- checked
    布尔型，匹配开关、勾选框、单选项等可确认状态。
- selected
    布尔型，匹配元素是否处于选中状态。
- index
    整数型，当有多个匹配项时取第几个，按 Lua 习惯从 `1` 开始。

## 说明

> 不建议把坐标、尺寸、窗口标识等容易变化的字段作为主要选择器。
> 多个元素同时匹配且没有指定 `index` 时，动作类接口可能返回 `nil, "ambiguous target"`。
> 不同 App、不同 iOS 版本暴露的字段可能不同，应为关键字段缺失预留处理逻辑。

---

Source: [! 给通讯录添加一个或多个联系人 (utils.add_contacts)](https://xxtouch.app/docs/handbook/utils/utils.add_contacts.md)
Path: handbook/utils/utils.add_contacts.md

# ! 给通讯录添加一个或多个联系人 (utils.add_contacts)


## 声明

```lua
操作成败 = utils.add_contacts({
    {
        firstName = "姓1",
        lastName = "名1",
        phoneNumbers = {
            "联系人1号码1",
            "联系人1号码2",
        },
        emails = {
            "联系人1邮箱1",
            "联系人1邮箱2",
        },
    },
    {
        firstName = "姓2",
        lastName = "名2",
        phoneNumbers = {
            "联系人2号码1",
            "联系人2号码2",
        },
        emails = {
            "联系人2邮箱1",
            "联系人2邮箱2",
        },
    },
    ...
})
```


## 参数

- firstName
    文本型，联系人姓
- lastName
    文本型，联系人名
- phoneNumbers
    表型，这个人的号码列表
- emails
    表型，这个人的邮箱号列表


## 返回值

- 操作成败
    布尔型，添加成功返回 true，失败返回 false


## 说明

> 将一个或多个联系人记录添加到系统通讯录
> **注意：大批量导入需要较长时间**


## 示例

```lua
utils.add_contacts({
    {
        firstName = "小",
        lastName = "明",
        phoneNumbers = {
            "13800001111",
            "13800002222",
        },
        emails = {
            "xiaoming@qq.com",
            "xiaoming@163.com",
        },
    },
    {
        firstName = "小",
        lastName = "红",
        phoneNumbers = {
            "13800003333",
            "13800004444",
        },
        emails = {
            "xiaohong@qq.com",
            "xiaohong@163.com",
        },
    },
})
```

---

Source: [创建一个 VPN 配置 (vpnconf.create)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.create.md)
Path: handbook/vpnconf/vpnconf.create.md

# 创建一个 VPN 配置 (vpnconf.create)


## 声明

```lua
创建成败 = vpnconf.create(配置表)
```


## 参数

- 配置表
    表型，用于描述需要创建的 VPN 配置的描述的字典


## 返回值

- 创建成败
    布尔型，创建成功返回 true，创建失败返回 false，创建失败通常是因为参数不全或错误


## 说明

> 用于快速创建一个 VPN 配置，不支持 IKEv2 类型创建


## 配置表支持的字段及意义

|字段名            |类型          |意义|
|-----------------|-------------|----|
|dispName         |文本型        |VPN 的显示名|
|VPNType          |文本型        |VPN 的类型，支持 `"PPTP"`、`"L2TP"`、`"IPSec"`|
|server           |文本型        |服务器地址|
|authorization    |文本型        |账号|
|password         |文本型        |密码|
|secret           |文本型，可选参数|密钥，PPTP 可不填|
|encrypLevel      |整数型，可选参数|加密级别，默认 `1`|
|group            |文本型，可选参数|群组名称，默认 `""`|
|VPNSendAllTraffic|整数型，可选参数|是否发送所有流量，默认 `1`|


## 示例

```lua
local success = vpnconf.create{
    dispName = 'DemoVPN',             -- VPN 的显示名
    VPNType = "L2TP",                 -- VPN 的类型，支持 PPTP、L2TP、IPSec（不支持 IKEv2）
    server = 'vpn.example.com',       -- 服务器地址
    authorization = 'your_account',   -- 账号
    password = 'your_password',       -- 密码
    secret = 'your_shared_secret',    -- 密钥，PPTP 可不填
    encrypLevel = 1,                  -- 加密级别，选填，默认 1
    group = '',                       -- 群组名称，选填，默认 ""
    VPNSendAllTraffic = 1,            -- 是否发送所有流量，选填，默认 1
}
if success then
    sys.alert('创建成功')
else
    sys.alert('创建失败，请检查配置参数是否完整且正确')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [展现一个 webview (webview.show)](https://xxtouch.app/docs/handbook/webview/webview.show.md)
Path: handbook/webview/webview.show.md

# 展现一个 webview (webview.show)


## 声明

```lua
webview.show { -- 所有参数皆为可选参数
    html = HTML内容,
    x = 原点横坐标,
    y = 原点纵坐标,
    width = 宽度,
    height = 高度,
    corner_radius = 圆角半径,
    alpha = 不透明度,
    animation_duration = 动画时间,
    rotate = 旋转角度,
    level = 窗体层级,
    opaque = 范围不透明,
    ignores_hit = 是否忽略触摸事件,
    can_drag = 是否能被拖动,
    is_secure = 是否为安全组件,
}
```


## 字段说明

- html
    - 文本型，可选参数，页面 html 内容。默认为 上次调用 webview.show 时候所设
- id
    - 整数型，可选参数，表示当前 webview 的 id，可使用不同的 id 来同时展现多个 webview，范围 1 ~ 1000，默认为 1
- x
    - 整数型，可选参数，距离左侧的距离。默认为 0
- y
    - 整数型，可选参数，距离顶端的距离。默认为 0
- width
    - 整数型，可选参数，弹出窗口的宽度。默认为 屏幕宽度
- height
    - 整数型，可选参数，弹出的窗口高度。默认为 屏幕高度
- alpha
    - 实数型，可选参数，不透明度，范围 0.0 ~ 1.0。默认为 1.0
- corner_radius
    - 实数型，可选参数，圆角半径，0.0 则是方角。默认为 0.0
- animation_duration
    - 实数型，可选参数，从上次状态到参数所设状态的动画时间。默认为 0.0
- rotate
    - 实数型，可选参数，旋转状态， 0.0 (竖屏) 、90.0 (横屏 Home 在右) 、180.0 (竖屏翻转) 、270.0 (横屏 Home 在左) 。默认为 0.0
- level
    - 实数型，可选参数，窗体层级，默认 1100.0
- opaque
    - 布尔型，可选参数，背景不透明选项，默认为 true 背景不透明
- ignores_hit
    - 布尔型，可选参数，用于设置忽略（不拦截）触摸事件，默认为 false 不忽略。该属性在 webview 创建后不可更改
- can_drag
    - 布尔型，可选参数，用于设置是否可拖拽移动 webview，默认为 false 不能拖动
- is_secure（**XXT 1.3.8 及以上版本可用**）
    - 布尔型，可选参数，iOS 13.2 及以上版本系统用于设置是否为安全组件，默认为 false 不是安全组件，设置为 true 则 webview 无法被截屏、取色、录屏

## 说明

> 让 webview 以参数设置的那样出现
> 除了 html 参数会保持上一次 show 的状态，其它参数一律会在调用时重设成默认值


## 示例

参考 [本章末尾的综合示例](/docs/handbook/webview/samples.md)

---

Source: [获取当前脚本包的元信息 (xpp.info)](https://xxtouch.app/docs/handbook/xpp/xpp.info.md)
Path: handbook/xpp/xpp.info.md

# 获取当前脚本包的元信息 (xpp.info)


## 声明

```lua
元信息 = xpp.info()
```


## 返回值

- 元信息
    表型，返回当前脚本包的元信息，如果当前正在运行的脚本不是脚本包，返回一个空表


## 说明

> 用于从运行着的脚本中获取当前脚本的元信息
> 脚本包标准参考 [XPP](/docs/XPP/index.md)


## 示例

```lua
local info = xpp.info()
```

---

Source: [获取 App 的应用存档路径 (app.data_path)](https://xxtouch.app/docs/handbook/app/app.data_path.md)
Path: handbook/app/app.data_path.md

# 获取 App 的应用存档路径 (app.data_path)


## 声明

```lua
存档路径 = app.data_path(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 存档路径
    文本型 或 nil，返回应用程序的存档路径，如果应用不存在则返回 nil


## 说明

> 获取 App 的应用存档路径


## 示例

```lua
path = app.data_path("com.tencent.mqq") -- 获得 QQ 的应用存档路径
```

---

Source: [清理所有应用程序钥匙串信息 (clear.all_keychain)](https://xxtouch.app/docs/handbook/clear/clear.all_keychain.md)
Path: handbook/clear/clear.all_keychain.md

# 清理所有应用程序钥匙串信息 (clear.all_keychain)


## 声明

```lua
clear.all_keychain()
```


## 说明

> 清理所有应用程序钥匙串信息
> **警告：该函数调用的效果不可逆**


## 示例

```lua
clear.all_keychain()
```

---

Source: [重启脚本 (os.restart)](https://xxtouch.app/docs/handbook/control-flow/os.restart.md)
Path: handbook/control-flow/os.restart.md

# 重启脚本 (os.restart)


## 声明

```lua
操作成败, 错误信息 = os.restart([ 脚本文件路径 ])
```


## 参数

- 脚本文件路径
    文本型，可选参数，当这里传入一个有效的脚本文件路径将会重启到目标脚本文件，默认为 `""`

## 返回值

- 操作成败
    布尔型，操作失败时返回 false；仅在传入 **脚本文件路径** 参数时才有可能失败；操作成功时函数不会返回（进程已重启）
- 错误信息
    文本型，操作失败时返回具体的错误信息


## 说明

> 未传入 **脚本文件路径** 时，该函数会直接重启 **当前脚本** 进程，当前脚本立即结束
> 传入有效的 **脚本文件路径** 时，当前脚本结束并重新启动到 **目标脚本文件**
> 操作失败时，函数返回 false 并附带错误信息；失败通常由非法参数导致


## 需要注意

> **当前脚本** 指启动时加载的那份脚本；脚本文件被修改后，`os.restart()` **不会** 加载修改后的文件
> 如无必要，请不要在多线程环境中使用该函数
> 零延迟重启可能引发其它逻辑问题，需由脚本作者自行规避


## 示例 1

```lua
os.restart() -- 重启到 “当前脚本” (不是 “当前脚本文件”)
```


## 示例 2

```lua
os.restart(utils.launch_args().path) -- 重启到 “当前脚本文件”
```
**注**：上述代码中使用了非本章函数 [`utils.launch_args`](/docs/handbook/utils/utils.launch_args.md)

---

Source: [创建一个 CoreML 视觉推理器 (coreml.new_vision_request)](https://xxtouch.app/docs/handbook/coreml/coreml.new_vision_request.md)
Path: handbook/coreml/coreml.new_vision_request.md

# 创建一个 CoreML 视觉推理器 (coreml.new_vision_request)

## 声明

```lua
视觉推理器对象, 错误信息 = coreml.new_vision_request(编译好的模型路径)
```

或

```lua
视觉推理器对象, 错误信息 = coreml.new_vision_request({
    compiled_model_path = 编译好的模型路径,
    uses_cpu_only = 是否只使用 CPU,
    compute_units = 计算单元配置,
    image_crop_and_scale_option = 裁切与缩放模式,
})
```

## 参数

- 编译好的模型路径
    文本型，目前支持图像分类和目标检测两种类型的模型

- uses_cpu_only
    布尔型，可选参数，是否默认只使用 CPU 推理，默认 `false`

- compute_units
    文本型，可选参数，**iOS 12+** 生效。支持以下值：
    - `"all"`
    - `"cpu_only"` 或 `"cpu"`
    - `"cpu_and_gpu"` 或 `"gpu"`
    - `"cpu_and_neural_engine"`、`"ane"` 或 `"neural_engine"`（**iOS 16+**）

- image_crop_and_scale_option
    整数型，可选参数，视觉推理时的裁切与缩放模式

## 返回值

- 视觉推理器对象
    视觉推理器对象，创建失败返回 `nil`

- 错误信息
    文本型，创建成功为 `nil`，失败时返回错误信息

## 说明

- **软件版本在 1.3.8 或以上方可使用**
- 不支持 iOS 13 以下版本系统
- 这个函数用于加载一个已经编译好的模型 `.mlmodelc` 返回一个用于图像推理的上下文
- 适用于以图像作为输入的 CoreML 视觉模型
- 如果模型输入本身是通用 `image` / `MLMultiArray` 特征，也可考虑使用 [coreml.new_model_request](coreml.new_model_request.md)
- 这个对象除了 `:predict()` / `:run()` 外，也支持 `:results()`、`:is_done()`、`:compute_units()`、`:image_crop_and_scale_option()`、`:class_labels()` 等查询方法

## 示例

参考 [使用 CoreML 视觉推理器对图像进行推理](coreml_vision_request_objectm_predict.md)

---

Source: [将打印缓冲区的内容提出来 (print.out)](https://xxtouch.app/docs/handbook/develop-helper/print.out.md)
Path: handbook/develop-helper/print.out.md

# 将打印缓冲区的内容提出来 (print.out)


## 声明

```lua
缓冲区内容 = print.out()
```

## 返回值

- 缓冲区内容
    文本型，`print` 打印缓冲区中累积的内容

## 说明

> 清空 `print` 的打印缓冲区，并返回其中累积的内容


## 示例

```lua
-- 使用一个弹窗显示 print 缓冲区内容
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [锁定屏幕 (device.lock_screen)](https://xxtouch.app/docs/handbook/device/device.lock_screen.md)
Path: handbook/device/device.lock_screen.md

# 锁定屏幕 (device.lock_screen)


## 声明

```lua
device.lock_screen()
```

## 示例

```lua
device.lock_screen()
```

---

Source: [配置对话框配置保存文件名 (:set_config)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_config.md)
Path: handbook/dialog/dialogm_set_config.md

# 配置对话框配置保存文件名 (:set_config)


## 声明

```lua
对话框对象 = 对话框对象:set_config(配置名)
```


## 参数

- 配置名
    文本型，配置对话框对象的选项配置保存名

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 对话框显示后，用户按下 **提交** 会保存配置选项；再次显示时会默认选中已保存的配置
> 配置将以文件形式保存在 /private/var/mobile/Media/1ferver/uicfg/**\<配置名\>**.xcfg


## 示例

```lua
dialog():set_config('配置名'):show()
```


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [深序列化一个表 (table.deep_dump)](https://xxtouch.app/docs/handbook/ext-table/table.deep_dump.md)
Path: handbook/ext-table/table.deep_dump.md

# 深序列化一个表 (table.deep_dump)


## 声明

```lua
表文本 = table.deep_dump(关联表)
```


## 参数

- 关联表
    表型，需要序列化成字符串的表

## 返回值

- 表文本
    文本型，表的树形结构文本；该格式不保证版本间兼容


## 说明

> 将表的树形结构序列化为文本
> 序列化结果 **不保证版本间兼容**，不同版本的输出可能不同
> 非表型引用类型（如 userdata、函数）无法被 [table.load_string](/docs/handbook/ext-table/table.load_string.md) 反序列化，仅保证人类可读性


## 示例

```lua
local s = table.deep_dump(_G)
sys.alert(s)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取目录所有文件名列表 (file.list)](https://xxtouch.app/docs/handbook/file/file.list.md)
Path: handbook/file/file.list.md

# 获取目录所有文件名列表 (file.list)


## 声明

```lua
文件列表, 错误信息 = file.list(文件路径 [, 深层完整遍历])
```


## 参数

- 文件路径
    文本型，目录绝对路径
- 深层完整遍历（自 20250313 版本起支持）
    布尔型，可选参数，是否递归遍历子目录并返回完整路径列表，默认 false

## 返回值

- 文件列表
    顺序表型 或 nil，如果目录不存在或路径是一个文件则返回 nil，否则返回目录文件列表
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获取目录所有文件名列表


## 示例

```lua
local list, err = file.list("/var/mobile/")
if list then
    print("目录 `/var/mobile/` 中有"..#list.."个文件或目录")
    for _, name in ipairs(list) do
        print(name)
    end
    sys.alert(print.out())
else
    sys.alert("`/var/mobile/` 不是目录："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

深层完整遍历示例
```lua
-- 完整文件路径列表 = file.list(文件路径, 深层完整遍历)
-- 获取一个目录的文件名列表，第二个参数用于控制是否递归获取子目录文件完全路径列表，默认为 false
list = file.list("/var/mobile/Media/1ferver", true)
nLog(list)
--[[
可能输出
{ -- table: 0xc4cc58a30
    [1] = "/var/mobile/Media/1ferver/snippets/syntax - do __ end.snippet",
    [2] = "/var/mobile/Media/1ferver/snippets/app - app.uninstall(bid).snippet",
    [3] = "/var/mobile/Media/1ferver/snippets/test - snippet.snippet",
    ...
}
--]]
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [FTP 文件上传 (ftp.upload)](https://xxtouch.app/docs/handbook/ftp/ftp.upload.md)
Path: handbook/ftp/ftp.upload.md

# FTP 文件上传 (ftp.upload)


## 声明

```lua
上传成败, 上传信息 = ftp.upload(本地文件路径, URL [, 连接超时秒, 断点续传模式, 分块回调函数, 缓冲区尺寸 ])
```

## 参数

- 本地文件路径
    文本型，本地文件路径
- URL
    文本型，需要上传到的远端地址，账号及密码被包含在这一参数中
- 连接超时秒
    实数型，可选参数，连接超时时间，单位秒，默认 10
- 断点续传模式
    布尔型，可选参数，是否需要支持断点续传，是为 true，否为 false，默认 false
- 分块回调函数
    函数型，可选参数，分块回调函数，每上传完一个分块都会回调一次该函数，默认 空函数
    分块回调函数第一个参数为当前上传的信息，回调函数返回 true 则打断这次上传
- 缓冲区尺寸
    整数型，可选参数，缓冲区大小字节数，默认自动最优配置

## 返回值

- 上传成败
    布尔型，连接是否成功
- 上传信息
    表型 或 文本型，如果连接成功则返回表型上传信息，否则返回连接失败原因文本描述


## 说明

```lua
-- 第二个返回值上传信息结构如下
{
    resource_size = 本地文件总字节数,
    start_pos = 本次上传从本地文件的开始的位置,
    size_upload = 本次上传的字节数,
    speed_upload = 本次上传的速度 (单位：字节/秒) ,
}
```
> 该函数适合大文件上传，在传输的过程中停止脚本可能会缓慢
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 简单示例

> 账号密码写在 URL 中，具体 URL 格式如下 \(中括号内是可选参数\)
```lua
ftp://[账号:密码@]地址[:端口]/路径
```
> 账号或密码中包含 `@`、`:`、`/` 这三个字符可分别用 `%40`、`%3A`、`%2F` 转义（其他在 URL 中非法的字符可使用 URL 百分号编码）
> 例如账号 `havonz`、密码 `11@@22`，示例如下：
```lua
local done, info = ftp.upload("/var/mobile/1.zip", "ftp://havonz:11%40%4022@192.168.31.13/1.zip")
if (done) then
    sys.alert("上传完成")
else
    sys.alert("连接失败："..info)
end
```


## 复杂示例

```lua
local done, info = ftp.upload("/var/mobile/1.zip", "ftp://havonz:123456@192.168.31.13/1.zip", 10, true, function(binfo)
    local percent = math.floor(((binfo.start_pos + binfo.size_upload) / binfo.resource_size) * 100)
    sys.toast("上传进度 "..percent.."%")
end, 4096 * 1024)
--
if (done) then
    if (info.start_pos + info.size_upload < info.resource_size) then
        sys.alert(
            "上传中断\n本次上传 "..info.size_upload.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始上传"
            .."\n平均速度为 "..math.floor(info.speed_upload/1024).." kB/s"
            .."\n还有剩 "..(info.resource_size - (info.start_pos + info.size_upload)).." 字节"
        )
    else
        sys.alert(
            "上传完成\n本次上传 "..info.size_upload.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始上传"
            .."\n平均速度为 "..math.floor(info.speed_upload/1024).." kB/s"
        )
    end
else
    sys.alert("连接失败："..info)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [按下手柄按键 (:down)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_down.md)
Path: handbook/gamepad/gamepadm_down.md

# 按下手柄按键 (:down)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:down(按键)
```

## 参数

- 按键
    整数型 或 文本型，可传入 `1` 至 `32` 的整数、下表中的按键名称，或 `"start"`、`"menu"`；字符串不区分大小写

| 编号 | 按键名称 | 别名 |
|---:|---|---|
| 1 | `a` | - |
| 2 | `b` | - |
| 3 | `x` | - |
| 4 | `y` | - |
| 5 | `left_shoulder` | `left_bumper`、`lb`、`l1` |
| 6 | `right_shoulder` | `right_bumper`、`rb`、`r1` |
| 7 | `left_trigger` | `lt`、`l2` |
| 8 | `right_trigger` | `rt`、`r2` |
| 9 | `left_stick` | `l3` |
| 10 | `right_stick` | `r3` |
| 11 | `l4` | `left_paddle` |
| 12 | `r4` | `right_paddle` |
| 13 | `m1` | - |
| 14 | `m2` | - |
| 15 | `m3` | - |
| 16 | `m4` | - |

## 返回值

- 状态
    布尔型，操作成功返回 true，设备断开、忙或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

- 数字 `1` 至 `32` 表示数字按键，不是跨设备统一的游戏按键码；通常应优先使用上表中的按键名称
- 数字 `17` 至 `32` 没有预定义名称，只有目标 App 支持相应扩展按键时才会产生效果
- `"start"` 和 `"menu"` 是同一个菜单输入的别名，不对应 `1` 至 `32` 中的某个数字
- `select`、`back`、`options`、`home`、`share` 和触摸板按键名称暂不支持
- `left_trigger` 和 `right_trigger` 只支持按下或松开，不支持模拟压力值；`menu` 不会触发系统主屏幕动作
- 参数类型错误、未知名称和越界值会作为 Lua 参数错误抛出，而不是返回 `false, error`

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:down("left_shoulder"))
assert(pad:up("left_shoulder"))
assert(pad:down(13))  -- 数字按键 13
assert(pad:up(13))
assert(pad:disconnect())
```

---

Source: [发起 GET 请求 (http.get)](https://xxtouch.app/docs/handbook/http/http.get.md)
Path: handbook/http/http.get.md

# 发起 GET 请求 (http.get)


## 声明

```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.get(URL [, 超时秒, 请求头, URL不ESCAPE ])
```

## 声明（命名参数）

**20250625 支持，20260402 以后版本支持进度参数**
```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.get{
    url = URL;
    timeout = 超时秒;
    headers = 请求头;
    params = Query参数;
    download_file = 请求成功返回主体保存文件路径;
    progress = 进度回调函数;
    progress_interval_ms = 进度回调间隔毫秒;
}
```


## 参数

- URL
    文本型，需要请求的 URL 地址，该方法默认会对 URL 进行百分号 escape 处理，如不需要可参考 **URL 不 ESCAPE** 参数说明
- 超时秒
    实数型，可选参数，请求超时时间，单位秒，默认 10
- 请求头
    表型，可选参数，发出的请求的头部信息，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- Query 参数
    表型，可选参数，发出的请求的 Query 参数，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求成功返回主体保存文件路径
    文本型，可选参数，如果有该参数，则请求成功后返回主体为保存的文件路径
- 进度回调函数
    函数型，可选参数，**20260402 以后版本支持**。请求进度变化时调用，回调函数第一个参数为当前进度信息
- 进度回调间隔毫秒
    整数型，可选参数，**20260402 以后版本支持**。控制进度回调触发间隔，单位毫秒
- **URL 不 ESCAPE**
    布尔型，可选参数，true 表示不对 URL 进行 escape 直接请求，默认 false
    对 URL 进行自定义 escape 可参考 [lcurl 模块](/docs/handbook/open-source/lcurl.md) 的 [easy:escape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:escape)、[easy:unescape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:unescape)


## 返回值

- HTTP 状态码
    整数型，返回当次请求的 http 状态码，请求超时返回 -1
- 返回头 JSON 文本
    文本型 或 nil，请求完成返回的 JSON 形式头部信息，请求超时返回 nil
- 返回主体
    字符串型 或 nil，请求完成返回的内容，如果请求主体保存到文件，则此值为文件路径，请求超时返回 nil


## 说明

> 使用 HTTP/1.1 协议的 GET 方法请求获取网络资源
> 该函数不会将资源存储到磁盘，若需下载较大的网络资源，建议使用 [http.download](/docs/handbook/http/http.download.md)
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**
> 若服务器协议版本为 HTTP/1.0 或 HTTP/0.9，可使用 httpGet 方法替代
```lua
返回主体 = httpGet(URL, 超时秒)
```

进度回调函数接收的 `info` 结构如下：

```lua
{
    count_of_bytes_sent = 已发送字节数;
    count_of_bytes_expected_to_send = 预计需要发送字节数;
    count_of_bytes_received = 已接收字节数;
    count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
```


## 示例

```lua
local code, res_headers, body = http.get("https://httpbin.org/get?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
    ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
})
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 示例（命名参数）

```lua
local code, res_headers, body = http.get{
    url = "https://httpbin.org/get";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
        ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
}
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## http.get 封装获取外网 IP 实例

```lua
function get_ip()
    local done = false
    thread.dispatch(function()
        while (true) do
            if (done) then
                sys.toast("", -1)
                return
            else
                sys.toast("正在获取 IP 地址...", device.front_orien())
            end
            sys.msleep(2000)
        end
    end)
    while (true) do
        local c, h, b = http.get("https://ip.chinaz.com/?ts="..tostring(sys.rnd()), 60)
        if (c==200) then
            sys.toast("", -1)
            done = true
            return b:match('您的本机IP地址：(%d%d?%d?%.%d%d?%d?%.%d%d?%d?%.%d%d?%d?)')
        end
    end
end
--
-- 将以上代码拷贝到自己的脚本最前面，然后在脚本中使用
sys.alert(get_ip())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`sys.rnd`](/docs/handbook/sys/sys.rnd.md)、[`thread.dispatch`](/docs/handbook/thread/thread.dispatch.md)、[`device.front_orien`](/docs/handbook/device/device.front_orien.md)

---

Source: [创建指定尺寸空白图片对象 (image.new)](https://xxtouch.app/docs/handbook/image/image.new.md)
Path: handbook/image/image.new.md

# 创建指定尺寸空白图片对象 (image.new)


## 声明

```lua
图片 = image.new(宽, 高)
```


## 参数

- 宽, 高
    整数型，新建的图片对象的宽、高

## 返回值

- 图片
    图片对象，返回新建的图片对象


## 说明

> 创建空白图片对象，默认这图片上所有的点的颜色皆为 0x000000 (黑)
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用

---

Source: [将 Lua 值转成 JSON 字符串 (json.encode)](https://xxtouch.app/docs/handbook/json/json.encode.md)
Path: handbook/json/json.encode.md

# 将 Lua 值转成 JSON 字符串 (json.encode)


## 声明

```lua
JSON文本, 错误信息 = json.encode(值)
```


## 参数

- 值
    表型 或 文本型 或 数值型 或 布尔型 或 json.null，需要转换成 json 文本的 lua 值

## 返回值

- **JSON 文本**
    文本型 或 nil，转换成功则返回一个 json 字符串，否则返回 nil
- 错误信息
    文本型 或 nil， 转换失败 **JSON 文本** 的值为 nil 的情况下，这个返回值则是具体的错误信息


## 说明

> 将 lua 中的数据值转成 json 形式可以方便与其它语言交互传输
> **注意** 不是任何 lua 值都可以转成 json。例如：用户数据或函数及包含用户数据或函数的表
> 该函数可在 XUI 中使用


## 示例

```lua
local tb = {
    ["name"] = "alice",
    ["message"] = "hello, world",
    scores = {
        90, 85, 72, 100, 68,
    },
    nullvalue = json.null,
}
local jsonstr = json.encode(tb)
sys.alert(jsonstr)
--
local tmp = json.decode(jsonstr)
sys.alert(tmp.scores[4])
sys.alert(tostring(tmp.nullvalue))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [模拟按下物理按键 (key.down)](https://xxtouch.app/docs/handbook/key/key.down.md)
Path: handbook/key/key.down.md

# 模拟按下物理按键 (key.down)

> **本页所述硬件键盘功能在 20260805 以后版本方可使用**

## 声明

```lua
key.down(按键码)
```

## 参数

- 按键码
    文本型，物理按键的按键码，键码在[示例及支持的键码列表](/docs/handbook/key/samples.md)一节查看。

## 说明

> 模拟按下物理按键。
> **注意：** 没有连接全局硬件键盘时，该函数应当有对应的 [`key.up`](/docs/handbook/key/key.up.md) 调用，否则脚本终止后可能出现按键持续不释放的问题。全局硬件键盘会在断开或脚本停止时释放全部已按下的按键。

- 连接[全局硬件键盘](key.connect_global_keyboard.md)后，普通键盘和数字小键盘按键会通过该对象输入；媒体键和厂商自定义键仍保持原有行为
- 本函数会与对应的 `key.up` 保持配对。若硬件键盘已经断开，按键会在断开时释放，后续 `key.up` 不会再次发送输入
- 通过 `key(...):down()` 调用时遵循相同规则

## 示例

参考[本章末尾的综合示例](/docs/handbook/key/samples.md)。

---

Source: [移动硬件鼠标 (:move)](https://xxtouch.app/docs/handbook/mouse/mousem_move.md)
Path: handbook/mouse/mousem_move.md

# 移动硬件鼠标 (:move)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:move(水平位移, 垂直位移)
```


## 参数

- 水平位移
    整数型，相对水平位移，范围 `[-2047, 2047]`；正数向右，负数向左
- 垂直位移
    整数型，相对垂直位移，范围 `[-2047, 2047]`；正数向下，负数向上


## 返回值

- 状态
    布尔型，移动成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，移动失败的原因


## 说明

> 相对当前位置移动一次。
> 接口不会自动拆分超出范围的位移，越界值会作为 Lua 参数错误抛出。


## 示例

```lua
local m = assert(mouse.connect())
assert(m:move(100, -50))
assert(m:disconnect())
```

---

Source: [ONNX Runtime 会话模块](https://xxtouch.app/docs/handbook/onnxruntime/onnxruntime.session_module.md)
Path: handbook/onnxruntime/onnxruntime.session_module.md

# ONNX Runtime 会话模块

> **该模块在 20260402 以后版本方可使用**

会话对象负责加载 ONNX 模型、查看输入输出信息以及执行推理。

## 运行时配置

### `onnxruntime.configure(opts)`

```lua
assert(onnxruntime.configure({
    log_severity_level = 2,
    log_id = "my-runtime",
    use_global_thread_pools = false,
    global_intra_op_num_threads = 0,
    global_inter_op_num_threads = 0,
}))
```

说明：

- 必须在创建任何 session 之前调用
- 一旦已有活动 session，继续调用会报错

支持字段：

- `log_severity_level`
- `log_id`
- `use_global_thread_pools`
- `global_intra_op_num_threads`
- `global_inter_op_num_threads`

## 创建会话

### `onnxruntime.session(model_path[, opts])`

```lua
会话对象, 错误信息 = onnxruntime.session(模型路径, 选项)
```

从文件路径加载 ONNX 模型。

### `onnxruntime.session_from_bytes(model_bytes[, opts])`

```lua
会话对象, 错误信息 = onnxruntime.session_from_bytes(模型字节串, 选项)
```

从内存字节创建会话。

## Session 选项

### 通用字段

- `providers` 或 `provider`
  可传单个字符串或字符串数组；当前原生处理并支持 `"cpu"`、`"coreml"`，也接受 `CPUExecutionProvider`、`CoreMLExecutionProvider` 这类别名
- `fallback_to_cpu`
  布尔型，默认 `true`
- `intra_op_num_threads`
- `inter_op_num_threads`
- `log_id`
- `session_log_severity_level`
- `session_log_verbosity_level`
- `optimized_model_path`
- `profile_file_prefix`
- `free_dimension_overrides`
- `config_entries`
- `graph_optimization_level`
  可选 `"disable"`、`"basic"`、`"extended"`、`"all"`
- `execution_mode`
  可选 `"sequential"`、`"parallel"`
- `deterministic_compute`
- `disable_per_session_threads`
- `enable_cpu_mem_arena`
- `enable_mem_pattern`
- `custom_op_libraries`

补充说明：

- `free_dimension_overrides` 需要传数组表，每项结构为 `{ by = "name"|"denotation", key = "...", value = 整数 }`
- `config_entries` 必须是“字符串键 -> 字符串值”的 table
- `custom_op_libraries` 可以是单个路径字符串、路径数组，或 `load_custom_op_library()` 返回的句柄；数组里也可以混用路径和句柄
- 如果没有显式指定 `providers`，或者 provider 列表为空，当前实现会默认补上 CPU provider
- 当 provider 列表里包含 `"coreml"` 且 `fallback_to_cpu = true` 时，CoreML provider 初始化失败后可自动回退到 CPU
- 如果你显式写成 `providers = {"coreml", "cpu"}`，顺序就表示先 CoreML、后 CPU

### CoreML provider 相关字段

当 `providers` 中包含 `"coreml"` 时，还可使用：

- `coreml_compute_units`
  推荐使用 `"all"`、`"cpu_only"`、`"cpu_and_gpu"`、`"cpu_and_neural_engine"`；解析器也兼容 `CPUOnly`、`CPUAndGPU`、`CPUAndNeuralEngine`、`MLComputeUnits...` 这些别名
- `coreml_create_mlprogram`
- `coreml_require_static_input_shapes`
- `coreml_enable_on_subgraph`
- `coreml_flags`
- `coreml_use_cpu_only`
- `coreml_use_cpu_and_gpu`
- `coreml_only_enable_device_with_ane`

补充说明：

- `coreml_flags`、`coreml_use_cpu_only`、`coreml_use_cpu_and_gpu`、`coreml_only_enable_device_with_ane` 都是兼容旧写法的字段
- 新旧字段可以混用，但如果表达的含义互相冲突，session 创建会直接报错
- `coreml_only_enable_device_with_ane` 不能和 `coreml_compute_units = "cpu_only"` / `"cpu_and_gpu"` 这类互斥配置同时使用

## 会话对象方法

### 基础信息

- `session:input_names()`
- `session:output_names()`
- `session:overridable_initializer_names()`
- `session:input_count()`
- `session:output_count()`
- `session:overridable_initializer_count()`

### 类型信息

- `session:input_info(name_or_index)`
- `session:output_info(name_or_index)`
- `session:overridable_initializer_info(name_or_index)`

返回值是类型信息表，常见字段包括：

- `name`
- `onnx_type`
- `is_sparse`
- `data_type`
- `type`
- `has_shape`
- `shape`
- `symbolic_shape`
- `element`
- `key_type`
- `value`

说明：

- tensor / sparse tensor 会带 `data_type`、`shape`、`symbolic_shape`
- sequence / optional 会带嵌套的 `element`
- map 会带 `key_type` 和嵌套的 `value`

### 内存信息

- `session:memory_info_for_inputs()`
- `session:memory_info_for_outputs()`

返回值既可以按顺序访问，也可以按名字访问。单项通常包含：

- `name`
- `id`
- `mem_type`
- `allocator_type`
- `device_type`
- `device_mem_type`
- `vendor_id`

### 元信息与生命周期

- `session:metadata()`
- `session:close()`
- `session:end_profiling()`
- `session:profiling_start_time_ns()`
- `session:set_ep_dynamic_options(opts)`
- `session:register_custom_op_library(path_or_handle)`

说明：

- `end_profiling()` 返回 profiling 输出文件路径
- `set_ep_dynamic_options()` 会把传入 table 的 key/value 都转成字符串再传给 ORT
- `register_custom_op_library()` 会在当前 session 选项基础上重建内部 session
- `path_or_handle` 既可以是路径，也可以是 `load_custom_op_library()` 返回的句柄

## 执行推理

### `session:run(inputs[, output_names[, run_options]])`

```lua
输出表, 错误信息 = session:run({
    input_ids = 输入张量,
    attention_mask = 掩码张量,
}, {
    "logits",
}, run_options)
```

### `session:run_into(inputs, outputs[, run_options])`

```lua
输出表, 错误信息 = session:run_into({
    x = 输入张量,
}, {
    y = 复用输出张量,
}, run_options)
```

### `session:run_with_iobinding(binding[, run_options])`

```lua
输出表, 错误信息 = session:run_with_iobinding(binding, run_options)
```

输入规则：

- `inputs` 可以是顺序数组，也可以是按输入名组织的字典
- 顺序数组按模型输入顺序匹配，后面也可以继续覆盖 overridable initializer
- 字典形式下，键必须与输入名或 overridable initializer 名一致
- optional 输入可以省略，也可以传 `onnxruntime.optional(nil, type_info)`

输出规则：

- 返回值是一个 table
- 同一个输出既可以用数字索引访问，也可以用输出名访问
- `run_into()` 如果某个输出复用了已有 tensor，返回表里对应项就是原对象本身

## Run Options

### `onnxruntime.run_options([opts])`

```lua
local run_options = assert(onnxruntime.run_options({
    tag = "session-run",
    log_severity_level = 2,
    log_verbosity_level = 1,
}))
```

支持字段：

- `tag`
- `log_severity_level`
- `log_verbosity_level`

对象方法：

- `run_options:tag([value])`
- `run_options:log_severity_level([value])`
- `run_options:log_verbosity_level([value])`
- `run_options:terminate()`
- `run_options:reset_terminate()`

## IOBinding

### `session:create_io_binding()`

```lua
binding, 错误信息 = session:create_io_binding()
```

### `binding:bind_input(name, value)`

绑定输入值。这里不接受空 optional。

### `binding:bind_output(name[, spec_or_tensor])`

支持三种形式：

- `binding:bind_output("y")`
  绑定到 CPU 内存，稍后通过 `get_outputs()` 取回
- `binding:bind_output("y", existing_tensor)`
  直接写入已有 tensor
- `binding:bind_output("y", {type = "float32", shape = {1, 2}})`
  由接口创建一个输出 tensor 并返回

也支持：

- `binding:bind_output("y", {mode = "device"})`

### 其它方法

- `binding:clear_inputs()`
- `binding:clear_outputs()`
- `binding:synchronize_inputs()`
- `binding:synchronize_outputs()`
- `binding:get_outputs()`

## 示例

```lua
local ort = require("onnxruntime")

local session = assert(ort.session(XXT_HOME_PATH.."/models/demo/model.onnx", {
    providers = {"coreml", "cpu"},
    fallback_to_cpu = true,
    coreml_compute_units = "all",
}))

local x = assert(ort.tensor("float32", {1, 2}, {1.0, 2.0}))
local bias = assert(ort.tensor("float32", {1, 2}, {0.5, -0.5}))
local run_options = assert(ort.run_options({tag = "demo"}))

local outputs = assert(session:run({
    x = x,
    bias = bias,
}, {"y"}, run_options))

print(outputs.y:to_table()[1])
```

---

Source: [LuaSocket 扩展库](https://xxtouch.app/docs/handbook/open-source/luasocket.md)
Path: handbook/open-source/luasocket.md

# LuaSocket 扩展库

[LuaSocket 手册地址](https://w3.impa.br/~diego/software/luasocket/reference.html)

---

## 连接超时示例

```lua
local socket = require("socket")
local sock = socket.tcp()
sock:settimeout(0.2) -- 设置连接超时秒数
if (sock:connect("220.181.57.217", 80)) then
    sock:close() -- 关闭连接
    sys.alert("能连上")
else
    sys.alert("超时了")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 模拟 HTTP 请求百度首页示例

```lua
local socket = require('socket')

local sock = socket.tcp()
local ip = assert(socket.dns.toip('www.baidu.com'), '域名解析失败')
sock:settimeout(10)
assert(sock:connect(ip, 80) == 1, '连接失败或超时')

assert(
    sock:send(
        'GET / HTTP/1.1\r\n'..
        'Host: www.baidu.com\r\n'..
        'Accept: */*\r\n'..
        'Connection: close\r\n'..
        '\r\n'
    ),
    '发送数据超时'
)

local buf = {}
repeat
    local chunk, status, partial = sock:receive(4096)
    if (chunk) then
        buf[#buf + 1] = chunk
    else
        if (partial) then
            buf[#buf + 1] = partial
        end
    end
until status == "closed"
sock:close()

sys.alert(table.concat(buf))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[table.concat](https://cloudwu.github.io/lua53doc/manual.html#pdf-table.concat)

---

Source: [写剪贴板项目 (pasteboard.write_items)](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.write_items.md)
Path: handbook/pasteboard/pasteboard.write_items.md

# 写剪贴板项目 (pasteboard.write_items)


## 声明

```lua
pasteboard.write_items(剪贴板项目 [, 选项 ])
pasteboard.write_items(剪贴板项目列表 [, 选项 ])
```


## 参数

- 剪贴板项目
    表型，键为 **通用类型标识**，值为字符串型数据
- 剪贴板项目列表
    表型，每项均为剪贴板项目
- 选项
    表型，可选参数
    `local_only` 布尔型，仅保存在本机，iOS 10 及以上支持
    `expiration_date` 数字型，Unix 时间戳，单位秒，iOS 10 及以上支持

    <details>

    <summary>剪贴板项目结构</summary>

    ```lua
    {
        ["public.utf8-plain-text"] = "普通文本",
        ["public.rtf"] = "RTF 数据",
        ["public.html"] = "HTML 数据",
        ["public.png"] = "PNG 二进制数据",
        ...
    }
    ```

    </details>


## 返回值

- 是否成功
    布尔型，写入成功返回 `true`，否则返回 `false`


## 说明

> 写剪贴板项目到系统剪贴板，可为同一个剪贴板项目提供多种格式表示
> iOS 9 会忽略 **选项** 参数
> **该函数在 20260428 以后版本方可使用**


## 示例

```lua
pasteboard.write_items({
    {
        ["public.utf8-plain-text"] = "normal bold italic red\n你好",
        ["public.rtf"] = [[{\rtf1\ansi\deff0
{\fonttbl{\f0 Helvetica;}}
{\colortbl;\red255\green0\blue0;}
\f0\fs32 normal {\b bold} {\i italic} \cf1 red\cf0\par
\u20320?\u22909?
}]],
        ["public.html"] = [[<p>normal <b>bold</b> <i>italic</i> <span style="color:red">red</span><br>你好</p>]],
    },
}, {
    local_only = true,
    expiration_date = os.time() + 3600,
})
```

---

Source: [写入属性表文件 (plist.write)](https://xxtouch.app/docs/handbook/plist/plist.write.md)
Path: handbook/plist/plist.write.md

# 写入属性表文件 (plist.write)


## 声明

```lua
plist.write(文件路径, 关联表)
```


## 参数

- 文件路径
    文本型，需要写入的 plist 文件的绝对路径
- 关联表
    表型，这个表的树形结构将会转换成 plist


## 说明

> 将一个表的树形结构写入到 plist 文件中
> 该函数可在 XUI 中使用


## 示例

```lua
local plfilename = "/var/mobile/Library/Caches/com.apple.mobile.installation.plist" -- 设置 plist 路径
local tmp2 = plist.read(plfilename)                        -- 读取 plist 文件内容并返回一个 table
tmp2["Metadata"]["ProductBuildVersion"] = "CustomBuild"    -- 将 ProductBuildVersion 键值改为 "CustomBuild"
plist.write(plfilename, tmp2)                              -- 将修改后的表写入 plist 文件
sys.chown(plfilename, 501, 501)                            -- 修正文件权限
sys.chmod(plfilename, "0644")                              -- 修正文件权限
```

---

Source: [查看进程字典存储的值 (proc_get)](https://xxtouch.app/docs/handbook/proc/proc_get.md)
Path: handbook/proc/proc_get.md

# 查看进程字典存储的值 (proc_get)


## 声明

```lua
值 = proc_get(键)
```


## 参数

- 键
    字符串型


## 返回值

- 值
    字符串型，返回该键位置存储的值，如果该键位置没有值则返回空字符串


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程词典全部被保留**
> 从进程词典的指定键位中读取值
> 如果该键位置原先没有值，则返回空字符串


## 示例

```lua
local bill = proc_get("billno")
if bill ~= "" then
    print("has a bill: ".. bill)
else
    print("no bill")
end
```

---

Source: [获取屏幕尺寸 (screen.size)](https://xxtouch.app/docs/handbook/screen/screen.size.md)
Path: handbook/screen/screen.size.md

# 获取屏幕尺寸 (screen.size)


## 声明

```lua
屏宽, 屏高 = screen.size()
```


## 返回值

- 屏宽 整数型
- 屏高 整数型


## 说明

> 该函数的返回值不受当前设备的桌面或应用的横竖屏状态影响，也不受放大模式影响
> 该函数可在 XUI 中使用


## 示例

```lua
-- 根据分辨率判断设备类型
width, height = screen.size()
if width == 640 and height == 1136 then
    -- iPhone 5, 5S, iPod touch 5
elseif width == 640 and height == 960 then
    -- iPhone 4, 4S, iPod touch 4
elseif width == 750 and height == 1334 then
    -- iPhone 6, 6S, 7, 8
elseif width == 1242 and height == 2208 then
    -- iPhone 6+, 6S+, 7+, 8+
elseif width == 768 and height == 1024 then
    -- iPad 1, 2, mini 1
elseif width == 1536 and height == 2048 then
    -- iPad 3, 4, 5, mini 2
elseif width == 320 and height == 480 then
    -- iPhone 3GS / iPhone 4（仅作完整性列出，XXTouch 不支持如此老旧的设备）
end
```

---

Source: [扩展库及远程扩展接口](https://xxtouch.app/docs/handbook/supplement/exts.md)
Path: handbook/supplement/exts.md

# 扩展库及远程扩展接口


## 扩展库

除 XXTouch 团队已编译的扩展库外，开发者也可自行为 XXTouch 扩展更多功能。欢迎下载模板尝试：
> [Lua 插件模板.zip](/zip/Lua插件模板.zip)


## 远程扩展接口

如有兴趣为 XXTouch 开发周边配套软件（例如局域网集中控制系统、截图取色工具、脚本开发调试环境、设备间数据共享等），请参阅：[OpenAPI](/OpenAPI/README.md)。

---

Source: [弹出系统提示 (sys.alert)](https://xxtouch.app/docs/handbook/sys/sys.alert.md)
Path: handbook/sys/sys.alert.md

# 弹出系统提示 (sys.alert)


## 声明

```lua
选择 = sys.alert(文字内容 [, 自动消失秒数, 标题, 按钮0标题, 按钮1标题, 按钮2标题 ])
```


## 参数

- 文字内容
    文本型， 代表弹出提示内容
- 自动消失秒数
    实数型，可选参数，代表弹窗自动消失时间，单位秒，设置 `0` 不自动消失，默认 `0`
- 标题
    文本型，可选参数，代表弹出提示的标题，默认 `"脚本提示"`
- 按钮 0 (取消按钮) 标题
    文本型，可选参数，代表弹出提示窗的默认按钮的标题，默认为 `"好"`
- 按钮 1 标题
    文本型，可选参数，代表弹出提示窗的额外的第 1 个按钮标题，默认不显示这个按钮
- 按钮 2 标题
    文本型，可选参数，代表弹出提示窗的额外的第 2 个按钮标题，默认不显示这个按钮

## 返回值

- 选择
    整数型
    - 返回 `0` 代表选择了 按钮 0（取消按钮）
    - 返回 `1` 代表选择了 按钮 1
    - 返回 `2` 代表选择了 按钮 2
    - 返回 `3` 代表到达自动消失秒数后超时关闭
    - 返回 `71` 代表 SpringBoard 在等待期间崩溃


## 说明

> 弹出一个系统提示对话框，最多可以有 3 个按钮，阻塞所有线程等待返回
> **20260108 以后版本该函数将在多任务环境让出**


## 示例

```lua
local choice = sys.alert('请选择一个操作', 10, '你的选择', '取消', '吃饭', '睡觉')
if choice==0 then
    sys.alert('你选择了「取消」')
elseif choice==1 then
    sys.alert('你选择了「吃饭」')
elseif choice==2 then
    sys.alert('你选择了「睡觉」')
elseif choice==3 then
    sys.alert('未选择，已超时')
else
    sys.alert('SpringBoard 崩溃')
end
```

---

Source: [Activator 事件回调消息](https://xxtouch.app/docs/handbook/system-callback/activator.md)
Path: handbook/system-callback/activator.md

# Activator 事件回调消息


## 声明

```lua
thread.register_event("xxtouch.activator_callback", function(val)
    local ret = json.decode(val)
    sys.toast("mode:"..ret.mode.."\n"
            .."event:"..ret.event.."\n"
            .."time:"..ret.time)
end)
```


## 状态

- val
    - 配置了 [Activator](https://cydia.saurik.com/package/libactivator/) 回调并触发相应事件时，事件详情会传递到此回调


## 说明

> 需要安装 [Activator](https://cydia.saurik.com/package/libactivator/) 并在其中完成相应配置后配合使用


## 示例

```lua
-- 清空消息队列
proc_queue_clear("xxtouch.activator_callback")
--
-- 开始建立监听回调
local eid = thread.register_event("xxtouch.activator_callback", function(val)
    local ret = json.decode(val)
    if ret.event=="libactivator.statusbar.tap.double" then
        sys.toast("双击状态栏回调")
    end
end)
--
sys.msleep(20000) -- 等待 20 秒
--
-- 反注册回调函数，如果不反注册监听，那么脚本不会在此结束
thread.unregister_event("xxtouch.activator_callback", eid)
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`proc_queue_clear`](/docs/handbook/proc/proc_queue_clear.md)、[`thread.register_event`](/docs/handbook/thread/thread.register_event.md)、[`thread.unregister_event`](/docs/handbook/thread/thread.unregister_event.md)

---

Source: [获取当前任务的 ID (thread.current_id)](https://xxtouch.app/docs/handbook/thread/thread.current_id.md)
Path: handbook/thread/thread.current_id.md

# 获取当前任务的 ID (thread.current_id)


## 声明

```lua
任务ID = thread.current_id()
```


## 返回值

- 任务 ID
    整数型，返回当前任务的 id


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [模拟手指接触屏幕 (touch.on)](https://xxtouch.app/docs/handbook/touch/touch.on.md)
Path: handbook/touch/touch.on.md

# 模拟手指接触屏幕 (touch.on)


## 声明

```lua
触摸事件 = touch.on(横坐标, 纵坐标)
```


## 参数

- 横坐标, 纵坐标
    整数型，需要接触的点于当前旋转坐标系的坐标


## 返回值

- 触摸事件
    触摸事件对象


## 说明

> 模拟手指接触屏幕指定位置，并返回一个用于操纵本次触摸过程的触摸事件对象
> 当前函数坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> **注:** 该函数会自动分配并占用一个手指 id，手指 id 的数量是有限的 (大约 30 个) ，超出限制再调用 [touch.on](/docs/handbook/touch/touch.on.md) 或 [touch.tap](/docs/handbook/touch/touch.tap.md) 会抛出 `finger pool overflow` 错误，注意不要**同时占用**过多手指 id，及时调用 :off 方法释放手指
> 该函数可同时使用以下方式调用（其中**手指 ID**必须是范围在 1 ~ 29 的任意数字，这种方式要自行管理手指 id）
```lua
touch.on(手指ID, 横坐标, 纵坐标)
```


## 示例

```lua
-- 模拟一个手指于点 100, 100 的位置接触屏幕，然后匀速滑动到点 200, 200 的位置，然后松开
touch.on(100, 100):move(200, 200):off()

touch.on(1, 100, 100) -- 模拟编号为 1 的手指于点 100, 100 的位置接触屏幕
touch.off(1)          -- 松开编号为 1 的手指
```

---

Source: [元素字段说明](https://xxtouch.app/docs/handbook/ui_element/element.md)
Path: handbook/ui_element/element.md

# 元素字段说明

> **该模块在 20260507 以后版本方可使用**

查询接口返回的元素是普通 Lua 表。字段来自当前界面暴露的信息，不同 App 与控件类型可能返回不同字段。

## 常见字段

- text
    文本型，元素的可读标题。
- value
    任意类型，元素当前值。文本框通常是当前文本，开关可能是 `0` 或 `1`，滑块可能是百分比文本。
- identifier
    文本型，元素标识符。
- hint
    文本型，系统辅助提示。
- bundleId
    文本型，元素所属 App 的 bundle identifier。
- x / y / width / height
    整数型，元素区域，单位为物理像素。
- centerPoint
    表型，元素中心点，单位为物理像素，例如 `{ x = 100, y = 200 }`。
- children
    表型，子元素数组。展开深度由 `max_level` 控制。
- traits
    整数型，元素特征值。
- traitsDescription
    表型，元素特征名称数组，例如 `Button`、`StaticText`、`Toggle`、`Adjustable`。
- isVisible
    布尔型，元素是否可见。
- isSelected
    布尔型，元素是否被选中。
- isToggle
    布尔型，元素是否像开关控件。
- isAdjustable
    布尔型，元素是否支持增减调节。
- checked
    布尔型，开关、勾选框、单选项等控件的确认状态。读不到可靠状态时可能不存在。
- hasTextEntry
    布尔型，元素是否像文本输入目标。
- isKeyboardKey
    布尔型，元素是否像键盘按键。
- absoluteValue
    实数型，滑块等可调节控件可能返回的归一化值。

## 命中状态字段

这些字段仅在启用 `include_hit_state`、`hit_test`、`fallback_hit_test` 或执行动作复核时可能出现：

- canHit
    布尔型，当前是否能从顶层命中。
- hitVerified
    布尔型，是否已经验证过命中状态。
- hitTestPoint
    表型，命中点，单位为物理像素。

## 说明

> 元素字段适合读取与判断当前界面状态。
> 如果需要稳定定位，优先使用 `text`、`role`、`checked`、`selected` 等语义字段组成选择器。
> 界面变化后应重新查询元素或重新获取快照。

---

Source: [删除通讯录所有联系人 (utils.remove_all_contacts)](https://xxtouch.app/docs/handbook/utils/utils.remove_all_contacts.md)
Path: handbook/utils/utils.remove_all_contacts.md

# 删除通讯录所有联系人 (utils.remove_all_contacts)


## 声明

```lua
操作成败 = utils.remove_all_contacts()
```


## 返回值

- 操作成败
    布尔型，删除成功返回 true，失败返回 false


## 说明

> 删除通讯录所有联系人
> 联系人数量较多时会需要一定时间


## 示例

```lua
utils.remove_all_contacts()
```

---

Source: [获取当前系统 VPN 的列表 (vpnconf.list)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.list.md)
Path: handbook/vpnconf/vpnconf.list.md

# 获取当前系统 VPN 的列表 (vpnconf.list)


## 声明

```lua
VPN列表 = vpnconf.list()
```


## 返回值

- VPN 列表
    表型 或 nil，获取成功返回当前系统 VPN 的顺序表，获取失败返回 nil

    <details>

    <summary>返回的 VPN 列表结构</summary>

    ```Lua
    {
        {dispName = 显示名 1, VPNID = VPNID1},
        {dispName = 显示名 2, VPNID = VPNID2},
        ...
    }
    ```
    </details>


## 示例

```lua
local list = vpnconf.list()
if list then
    sys.alert(table.deep_dump(list))
else
    sys.alert('获取 VPN 列表失败')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`table.deep_dump`](/docs/handbook/ext-table/table.deep_dump.md)

---

Source: [隐藏一个 webview (webview.hide)](https://xxtouch.app/docs/handbook/webview/webview.hide.md)
Path: handbook/webview/webview.hide.md

# 隐藏一个 webview (webview.hide)


## 声明

```lua
webview.hide([ id ])
```


## 参数

- id
    整数型，可选参数，表示当前 webview 的 id，范围 1 ~ 1000，默认为 1


## 说明

> 暂时隐藏一个 webview


## 示例

参考 [本章末尾的综合示例](/docs/handbook/webview/samples.md)

---

Source: [获取当前脚本包的包路径 (xpp.bundle_path)](https://xxtouch.app/docs/handbook/xpp/xpp.bundle_path.md)
Path: handbook/xpp/xpp.bundle_path.md

# 获取当前脚本包的包路径 (xpp.bundle_path)

## 声明

```lua
包路径 = xpp.bundle_path()
```


## 返回值

- 包路径
    文本型，返回当前脚本包的包路径，如果当前正在运行的脚本不是脚本包，返回当前运行的脚本路径


## 说明

> 用于从运行着的脚本中获取当前脚本的包路径
> 脚本包标准参考 [XPP](/docs/XPP/index.md)


## 示例

```lua
local path = xpp.bundle_path()
```

---

Source: [获取屏幕缩放因子 (screen.scale_factor)](https://xxtouch.app/docs/handbook/screen/screen.scale_factor.md)
Path: handbook/screen/screen.scale_factor.md

# 获取屏幕缩放因子 (screen.scale_factor)


## 声明

```lua
local factor = screen.scale_factor()
```


## 返回值

- factor
    数值型，表示当前设备屏幕像素与逻辑点 (pt) 之间的倍率


## 说明

> 返回值用于在屏幕实际像素分辨率与逻辑坐标系之间进行换算。
> 常见值：2.0（大部分 Retina iPhone 与 iPad）、3.0（Plus/Max 系列与近年的全面屏 iPhone）。现代 iPhone 基本没有 1.0 倍非 Retina。
> 与 `screen.size()` 联用可折算逻辑点尺寸：`width_pt = width_px / factor`。找图、取色依旧基于像素尺寸，只有在处理基于 UI 的点坐标时才需要转换。


## 示例

```lua
-- 将像素分辨率换算成逻辑点
local w_px, h_px = screen.size()
local scale = screen.scale_factor()
local w_pt, h_pt = w_px / scale, h_px / scale

sys.log(string.format("像素分辨率: %dx%d, 倍率: %.1fx, 逻辑点: %.0fx%.0f", w_px, h_px, scale, w_pt, h_pt))

-- 根据缩放因子调整 UI 坐标
local x_point, y_point = 100, 200           -- 来源于苹果 HIG 或第三方 UI 描述的点坐标
local x_px, y_px = x_point * scale, y_point * scale

touch.tap(x_px, y_px)
```
**注**：上述代码中使用了非本章函数 [`sys.log`](/docs/handbook/sys/sys.log.md)、[`touch.tap`](/docs/handbook/touch/touch.tap.md)

---

Source: [获取 App 的应用分组信息 (app.group_info)](https://xxtouch.app/docs/handbook/app/app.group_info.md)
Path: handbook/app/app.group_info.md

# 获取 App 的应用分组信息 (app.group_info)


## 声明

```lua
应用分组信息 = app.group_info(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 应用分组信息
    表型，返回应用程序的分组信息，格式为 `{group_id = data_path, ...}`。若不存在则返回空表


## 示例

```lua
local function clear_dir(path)
    for _, fn in ipairs(file.list(path) or {}) do
        local full_path = path .. '/' .. fn
        file.remove(full_path)
    end
end
--
local info = app.group_info("com.tencent.mqq") -- 获得 QQ 的分组信息
--
-- 循环删除所有分组目录中的内容
for _,p in pairs(info) do
    for _,v in ipairs(file.list(p) or {}) do
        local path = p .. '/' .. v
        if file.exists(path) == 'directory' then
            clear_dir(path)
        elseif v ~= '.com.apple.mobile_container_manager.metadata.plist' then
            file.remove(path)
        end
    end
end
```

---

Source: [清理浏览器 Cookies (clear.cookies)](https://xxtouch.app/docs/handbook/clear/clear.cookies.md)
Path: handbook/clear/clear.cookies.md

# 清理浏览器 Cookies (clear.cookies)


## 声明

```lua
clear.cookies()
```


## 说明

> 清理浏览器 Cookies
> **警告：该函数调用的效果不可逆**


## 示例

```lua
clear.cookies()
```

---

Source: [注册终止回调 (register_atexit)](https://xxtouch.app/docs/handbook/control-flow/register_atexit.md)
Path: handbook/control-flow/register_atexit.md

# 注册终止回调 (register_atexit)


## 声明

```lua
original_callback = register_atexit(name, callback)
```


## 参数

- name
    文本型，必填，用于标识当前注册的回调；使用相同的 `name` 会覆盖已注册的回调
- callback
    函数型，必填，在脚本退出时执行的函数，请确保其执行迅速并可安全重复调用。如果为 nil 则表示取消注册当前 `name` 的回调


## 返回值

- original_callback
    函数型，被同名注册覆盖前的旧回调；若之前未注册则返回 `nil`，可以用来恢复旧回调


## 说明

> `register_atexit` 注册的回调会在脚本退出、包含用户使用 **音量键** 结束脚本的情况下执行，并保证在 Lua 进行垃圾回收之前调用
> 当使用不同的 `name` 注册多个回调时，它们的调用顺序不受控制；如需要顺序执行，请在单个回调中自行调度
> 回调中如需调用耗时操作，请自行限制时长，否则可能影响退出体验
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
register_atexit("cleanup", function()
    sys.toast("脚本退出前清理资源")
    sys.msleep(300)
end)

while true do
    sys.toast("使用音量键尝试退出脚本\n" .. os.date("%Y-%m-%d %H:%M:%S"))
    sys.msleep(1000)
end
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [! 使用 CoreML 推理器对图像进行推理 (:predict)](https://xxtouch.app/docs/handbook/coreml/coreml_vision_request_objectm_predict.md)
Path: handbook/coreml/coreml_vision_request_objectm_predict.md

# ! 使用 CoreML 推理器对图像进行推理 (:predict)

## 声明

```lua
返回结果, 错误信息 = 视觉推理器对象:predict(需要推理的图片)
```

或

```lua
是否已提交, 错误信息 = 视觉推理器对象:predict(需要推理的图片, {
    async = 是否异步,
    multi_array_output = "table" 或 "MLMultiArray",
    uses_cpu_only = 是否本次只使用 CPU,
})
```

## 参数

- 需要推理的图片
    [图片对象](/docs/handbook/image/index.md)，需要进行推理的图像参数

- async
    布尔型，可选参数，传 `true` 时异步提交推理，默认 `false`

- multi_array_output
    文本型，可选参数，当返回 `MLMultiArray` 特征值时，指定返回 `"table"` 或 `"MLMultiArray"`，默认 `"table"`

- uses_cpu_only
    布尔型，可选参数，仅影响本次推理，传 `true` 时本次只使用 CPU

## 返回值

- 返回结果
    表型
    <details>

    <summary>目标检测模型返回结构</summary>

    ```lua
    {
        {
            ["y"] = number_value,
            ["x"] = number_value,
            ["w"] = number_value,
            ["h"] = number_value,
            ["confidence"] = number_value(0.0 ~ 100.0),
            ["name"] = string_value,
        },
        ...
    }
    ```
    </details>

    <details>

    <summary>图像分类模型返回结构</summary>

    ```lua
    {
        {
            ["confidence"] = number_value(0.0 ~ 100.0),
            ["name"] = string_value,
        },
        ...
    }
    ```
    </details>

    <details>

    <summary>其它类型模型返回结构</summary>

    ```lua
    {
        ...
    }
    ```
    </details>

## 说明

- **软件版本在 1.3.8 或以上方可使用**
- 不支持 iOS 12 以下版本系统
- 使用图像推理上下文对图像进行推理并返回推理结果
- 如果模型返回的是 `MLMultiArray` 特征值，可通过 `multi_array_output = "MLMultiArray"` 保留原生张量对象，便于继续后处理
- `:run()` 是 `:predict()` 的别名；异步提交后可用 `:is_done()` 和 `:results()` 读取结果
- 视觉推理器对象还支持 `:metadata()`、`:compute_units()`、`:image_crop_and_scale_option()`、`:class_labels()`、`:is_vision_request()` 等方法


## 示例

```lua
compiled_model_path = XXT_HOME_PATH..'/models/yolo11m.mlmodelc' -- 编译好的模型存放位置

file.remove(compiled_model_path) -- 测试阶段每次重新编译，模型稳定后可注释掉此行

if not file.exists(compiled_model_path) then -- 如果还没有编译好的模型，则编译一份
    local tmp_path, err = coreml.compile_model(XXT_HOME_PATH..'/models/yolo11m.mlpackage') -- 编译模型
    if not tmp_path then
        error(err)
    end
    file.move(tmp_path, compiled_model_path, 'mo') -- 将编译好的模型移动到指定位置
end

vnrequest, err = coreml.new_vision_request(compiled_model_path) -- 从模型创建推理器
if not vnrequest then
    error(err)
end

rets = vnrequest:predict(screen.image()) -- 使用推理器推理图片
nLog(rets)
```

---

Source: [网络日志 (nLog)](https://xxtouch.app/docs/handbook/develop-helper/nLog.md)
Path: handbook/develop-helper/nLog.md

# 网络日志 (nLog)


## 声明

```lua
nLog(日志内容)
```

## 参数

- 日志内容
    文本型，日志内容

## 说明

> 该函数为协议函数（空函数），默认执行不会产生任何效果，实现细节由配套开发环境决定
> 使用配套开发环境调试时，该函数会将日志发回开发环境的日志窗口

## 示例

```lua
-- 将 print 缓冲区内容发回开发工具的日志窗
nLog(print.out())
```

---

Source: [解锁屏幕 (device.unlock_screen)](https://xxtouch.app/docs/handbook/device/device.unlock_screen.md)
Path: handbook/device/device.unlock_screen.md

# 解锁屏幕 (device.unlock_screen)


## 声明

```lua
device.unlock_screen([ 锁屏密码 ])
```


## 参数

- 锁屏密码
    文本型，可选参数，锁屏密码，如果有锁屏密码也可以使用这个参数，如果没有则不填即可，不推荐使用

## 说明

> 使用锁屏密码解锁屏幕只在完整越狱环境并开启插件注入才有效，巨魔版无法使用锁屏密码解锁


## 示例

```lua
device.unlock_screen()
```

---

Source: [配置对话框自动消失时间 (:set_timeout)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_timeout.md)
Path: handbook/dialog/dialogm_set_timeout.md

# 配置对话框自动消失时间 (:set_timeout)


## 声明

```lua
对话框对象 = 对话框对象:set_timeout(超时秒[, 是否提交])
```


## 参数

- 超时秒
    实数型，对话框对象自动消失时间，单位秒
- 是否提交
    布尔型，可选参数，超时自动消失时是否视为提交；true 为提交、false 为不提交，默认 false

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 配置对话框自动消失时间


## 示例

```lua
dialog():set_timeout(3):show() -- 3 秒超时取消提交
--
dialog():set_timeout(3, true):show() -- 3 秒超时并提交
```

---

Source: [从序列化文本加载一个表 (table.load_string)](https://xxtouch.app/docs/handbook/ext-table/table.load_string.md)
Path: handbook/ext-table/table.load_string.md

# 从序列化文本加载一个表 (table.load_string)


## 声明

```lua
关联表 = table.load_string(表文本)
```


## 参数

- 表文本
    文本型，表的序列化树形结构的文本，只能包含静态数据，不能包含任何动态代码

## 返回值

- 关联表
    表型 或 nil，加载成功返回表结构，失败返回 nil


## 说明

> 将树形结构的文本描述转换为表对象
> 一定程度上，[table.load_string](/docs/handbook/ext-table/table.load_string.md) 可视为 [table.deep_dump](/docs/handbook/ext-table/table.deep_dump.md) 的反函数（实际可用程度取决于是否存在循环引用或非表型引用类型）
> 与 [load](https://cloudwu.github.io/lua53doc/manual.html#pdf-load) 不同：该函数不会执行文本中的代码，只读取其中的静态数据
> 下面的示例含有可执行代码，运行后 `b` 为 nil（代码不会执行）
```lua
b = table.load_string[[ {
    a = os.execute('reboot'), -- 这里的代码将不会运行，并且会返回 nil
} ]]
```


## 示例

```lua
local t = table.load_string[[ {
    a = 1,
    b = 2,
    c = 3,
} ]]
sys.alert(t.b)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获得一个文件的尺寸 (file.size)](https://xxtouch.app/docs/handbook/file/file.size.md)
Path: handbook/file/file.size.md

# 获得一个文件的尺寸 (file.size)


## 声明

```lua
尺寸, 错误信息 = file.size(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- 尺寸
    整数型 或 nil，如果文件不存在或文件名是一个目录则返回 nil，否则返回文件尺寸 (单位: 字节)
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获得一个文件的尺寸


## 示例

```lua
local fsize, err = file.size("/var/mobile/1.zip")
if fsize then
    sys.alert("`/var/mobile/1.zip` 的尺寸为："..fsize.."字节")
else
    sys.alert("`/var/mobile/1.zip` 不是文件："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [FTP 执行命令 (ftp.cmd)](https://xxtouch.app/docs/handbook/ftp/ftp.cmd.md)
Path: handbook/ftp/ftp.cmd.md

# FTP 执行命令 (ftp.cmd)

## 声明

```lua
result, err = ftp.cmd(URL, cmd [, connectTimeoutSec ])
```

## 参数

- URL
    文本型，FTP 远端地址，账号及密码包含在这一参数中；执行目录操作时应使用以 `/` 结尾的目录 URL
- cmd
    文本型，一条 FTP 协议命令，例如 `MKD test`，不支持传入命令表
- connectTimeoutSec
    实数型，可选参数，连接超时时间，单位秒，默认 10；不限制整个请求的总耗时

## 返回值

- result
    文本型 或 nil，请求成功时返回收到的数据，可能为空字符串；使用目录 URL 时通常为目录列表，不是 FTP 命令的状态码或控制连接回复；失败时返回 nil
- err
    文本型 或 nil，失败时返回错误原因文本描述；成功时不返回第二个值，接收变量为 nil

## 说明

向 FTP 服务器发送命令，可用于创建目录等操作，操作对象是服务器上的文件或目录。

命令在切换到 URL 指定的目录之前执行。相对路径以登录后的默认目录为基准；例如 `MKD uploads/test` 在该目录下的 uploads 中创建 test。不要依靠 URL 中的路径改变命令的执行目录；命令中的路径直接发送，不进行 URL 百分号解码。

`MKD` 通常只创建一级目录，父目录需要已经存在。目录已存在、账号没有权限或服务器不支持相应命令时，都可能失败。创建多级目录需要按父目录到子目录的顺序分别调用。

当前实现只要命令文本包含大写的 `LIST` 或 `NLST`，就会跳过发送该命令，仅执行 URL 的默认请求；即使这些片段出现在目录名中也一样。因此 `NLST` 不会切换成仅文件名列表，`LIST -a` 的参数也不会生效。

> **执行命令后仍会请求 URL 对应的数据，使用目录 URL 时还会获取目录列表。如果后续列目录或数据连接失败，目录可能已经创建，但函数仍返回 nil 和错误信息。**
> **该函数可能会让出，在其返回之前，其他 [线程](../thread/README.md) 可能会得到运行机会**

## 简单示例

> 账号密码写在 URL 中，具体 URL 格式如下（中括号内是可选部分）：

```lua
ftp://[user:password@]host[:port]/path
```

> 账号或密码中包含 `@`、`:`、`/` 这三个字符可分别用 `%40`、`%3A`、`%2F` 转义（其他在 URL 中非法的字符可使用 URL 百分号编码）。
> 例如账号 `havonz`、密码 `11@@22`，在登录后的默认目录下创建 test：

```lua
local result, err = ftp.cmd("ftp://havonz:11%40%4022@192.168.31.13/", "MKD test", 10)
if result == nil then
    sys.alert("创建失败：" .. tostring(err))
else
    sys.alert("创建成功")
end
```

## 复杂示例

依次创建 demo 和 demo/logs，两者均应尚不存在。某一步失败就停止，不自动删除此前已创建的目录。

```lua
local url = "ftp://havonz:11%40%4022@192.168.31.13/"

for _, path in ipairs({ "demo", "demo/logs" }) do
    local result, err = ftp.cmd(url, "MKD " .. path, 10)
    if result == nil then
        sys.alert("创建失败 " .. path .. ": " .. tostring(err))
        return
    end
end

sys.alert("目录创建完成")
```

**注**：上述代码中使用了非本章函数 [`sys.alert`](../sys/sys.alert.md)。

---

Source: [松开手柄按键 (:up)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_up.md)
Path: handbook/gamepad/gamepadm_up.md

# 松开手柄按键 (:up)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:up(按键)
```

## 参数

- 按键
    整数型 或 文本型，支持的编号和名称见 [按键参数说明](gamepadm_down.md)

## 返回值

- 状态
    布尔型，操作成功返回 true，设备断开、忙或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

> 松开指定按键。参数类型错误、未知名称和越界值会作为 Lua 参数错误抛出。

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:down("left_shoulder"))
assert(pad:up("left_shoulder"))
assert(pad:down(13))
assert(pad:up(13))
assert(pad:disconnect())
```

---

Source: [发起 POST 请求 (http.post)](https://xxtouch.app/docs/handbook/http/http.post.md)
Path: handbook/http/http.post.md

# 发起 POST 请求 (http.post)


## 声明

```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.post(URL [, 超时秒, 请求头, 请求主体数据, URL不ESCAPE ])
```

## 声明（命名参数）

**20250625 支持，20260402 以后版本支持进度参数**
```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.post{
    url = URL;
    timeout = 超时秒;
    headers = 请求头;
    params = Query参数;

    -- 以下请求主体参数不可并存，优先顺序为 multipart > data > json > upload_file
    multipart = 请求主体multipart表单;
    data = 请求主体数据;
    json = 请求主体JSON;
    upload_file = 请求主体上传文件路径;

    download_file = 请求成功返回主体保存文件路径;
    progress = 进度回调函数;
    progress_interval_ms = 进度回调间隔毫秒;
}
```


## 参数

- URL
    文本型，需要请求的 URL 地址，该方法默认会对 URL 进行 escape 处理，如不需要可参考 **URL 不 ESCAPE** 参数说明
- 超时秒
    实数型，可选参数，请求超时时间，单位秒，默认 10
- 请求头
    表型，可选参数，发出的请求的头部信息，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- Query 参数
    表型，可选参数，发出的请求的 Query 参数，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体数据
    字符串型，可选参数，使用 post 发送出去的内容，默认是空字符串
    **20250625** 如果为表型，则以 application/x-www-form-urlencoded 的方式编码发送
- 请求主体 multipart 表单
    表型，可选参数，使用 post 发送出去的 multipart 表单数据，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体 JSON
    表型，可选参数，以 application/json 的方式编码发送
- 请求主体上传文件路径
    文本型，可选参数，将文件数据直接作为请求体发送
- 请求成功返回主体保存文件路径
    文本型，可选参数，如果有该参数，则请求成功后返回主体为保存的文件路径
- 进度回调函数
    函数型，可选参数，**20260402 以后版本支持**。请求上传或下载进度变化时调用，回调函数第一个参数为当前进度信息
- 进度回调间隔毫秒
    整数型，可选参数，**20260402 以后版本支持**。控制进度回调触发间隔，单位毫秒
- **URL 不 ESCAPE**
    布尔型，可选参数，true 表示不对 URL 进行 escape 直接请求，默认 false
    对 URL 进行自定义 escape 可参考 [lcurl 模块](/docs/handbook/open-source/lcurl.md) 的 [easy:escape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:escape)、[easy:unescape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:unescape)


## 返回值

- HTTP 状态码
    整数型，返回当次请求的 http 状态码，请求超时返回 -1
- 返回头 JSON 文本
    文本型 或 nil，请求完成返回的 JSON 形式头部信息，请求超时返回 nil
- 返回主体
    字符串型 或 nil，请求完成返回的内容，如果请求主体保存到文件，则此值为文件路径，请求超时返回 nil


## 说明

> 使用 HTTP/1.1 协议的 POST 方法发送数据到网络中
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**
> 若服务器协议版本为 HTTP/1.0 或 HTTP/0.9，可使用
```lua
返回主体 = httpPost(URL, 字符串型请求主体数据, 超时秒)
```
> 该方法替代

进度回调函数接收的 `info` 结构如下：

```lua
{
    count_of_bytes_sent = 已发送字节数;
    count_of_bytes_expected_to_send = 预计需要发送字节数;
    count_of_bytes_received = 已接收字节数;
    count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
```


## 示例

```lua
local code, res_headers, body = http.post("https://httpbin.org/post?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)", -- 模拟 IE8 的请求
    ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
}, "需要发送过去的数据")
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

## 示例（命名参数）

```lua
local code, res_headers, body = http.post{
    url = "https://httpbin.org/post";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
        ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
    data = "需要发送过去的数据";
}
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## POST 提交表单示例

```lua
local c, h, r = http.post('https://httpbin.org/post', 60, {}, 'name=alice&email=alice%40example.com')
if (c == 200) then
    sys.alert(r, 0, '提交成功')
else
    if (c == -1) then
        sys.alert('请求失败，请检查网络连接', 0, '连接超时')
    else
        sys.alert('错误代码 #'..c..'\n'..r, 0, 'HTTP 错误')
    end
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [图像合并 (image.oper_merge)](https://xxtouch.app/docs/handbook/image/image.oper_merge.md)
Path: handbook/image/image.oper_merge.md

# 图像合并 (image.oper_merge)


## 声明

```lua
操作成败 = image.oper_merge(图片文件名数组, 输出路径, 合并类型, 生成质量)
```


## 参数

- 图片文件名数组
    表型，需合并图片的文件名列表，支持使用绝对路径
- 输出路径
    文本型，生成新图片的文件名，支持使用绝对路径
- 合并类型
    整数型，合并类型，0 - 横向合并；1 - 竖向合并
- 生成质量
    实数型，当生成图片格式为 jpg 时，可控制图片质量，范围 0.0 ~ 1.0

## 返回值

- 操作成败
    整数型，0 - 成功；1 - 失败；2 - 失败；3 - 失败


## 说明

> 相对路径将基于 `/var/mobile/Media/1ferver/res/` 解析；如需指定其他目录，请使用绝对路径


## 示例

```lua
image.oper_merge({"1.png","2.png","3.png"}, "4.jpg", 0, 0.5)
```

---

Source: [将 JSON 字符串转换成 Lua 值 (json.decode)](https://xxtouch.app/docs/handbook/json/json.decode.md)
Path: handbook/json/json.decode.md

# 将 JSON 字符串转换成 Lua 值 (json.decode)


## 声明

```lua
值, 错误信息 = json.decode(JSON文本)
```

## 参数

- JSON 文本
    文本型，需要转换成表的 json 文本

## 返回值

- **值**
    表型 或 文本型 或 数值型 或 布尔型 或 json.null 或 nil，转换成功则返回一个与 json 字符串结构相对应的 lua 值，否则返回 nil
- 错误信息
    文本型 或 nil， 转换失败 **值** 为 nil 的情况下，这个返回值则是具体的错误信息


## 说明

> 将 json 文本转换成 lua 的中对应的数据值
> 该函数可在 XUI 中使用


## 示例

```lua
print(json.decode('true'))
print(json.decode('17'))
print(json.decode('"哈哈"'))
print(json.decode('null'))
print(json.decode(''))
print(table.deep_dump(json.decode('{}')))
print(table.deep_dump(json.decode('{"name":"alice","hello":"world"}')))
print(table.deep_dump(json.decode('[]')))
print(table.deep_dump(json.decode('[1, 2, 3, "foo"]')))
--
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`table.deep_dump`](/docs/handbook/ext-table/table.deep_dump.md) 、[`print.out`](/docs/handbook/develop-helper/print.md)、[`sys.alert`](/docs/handbook/sys/sys.alert.md)

```lua
-- 使用 json.decode 将 \uXXXX 形式的 Unicode 转义还原为文字
sys.alert(json.decode([["\u4f60\u597d"]])) -- 输出：你好
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [松开按下的物理按键 (key.up)](https://xxtouch.app/docs/handbook/key/key.up.md)
Path: handbook/key/key.up.md

# 松开按下的物理按键 (key.up)

> **本页所述硬件键盘功能在 20260805 以后版本方可使用**

## 声明

```lua
key.up(按键码)
```

## 参数

- 按键码
    文本型，物理按键的按键码，键码在[示例及支持的键码列表](/docs/handbook/key/samples.md)一节查看。

## 说明

> 模拟松开按下的物理按键。

- 本函数会与对应的 `key.down` 保持配对，即使两次调用之间全局硬件键盘的连接状态发生变化，也不会造成重复输入或错误释放
- 没有对应 `key.down` 时，普通键盘和数字小键盘按键会使用当前[全局硬件键盘](key.connect_global_keyboard.md)；媒体键和厂商自定义键仍保持原有行为
- 通过 `key(...):up()` 调用时遵循相同规则

## 示例

参考[本章末尾的综合示例](/docs/handbook/key/samples.md)。

---

Source: [按下硬件鼠标按键 (:down)](https://xxtouch.app/docs/handbook/mouse/mousem_down.md)
Path: handbook/mouse/mousem_down.md

# 按下硬件鼠标按键 (:down)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:down(按键)
```


## 参数

- 按键
    整数型或文本型，可传入 `1` ~ `32`，或下表中的按键名称；字符串不区分大小写


## 返回值

- 状态
    布尔型，按下成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，按下失败的原因


## 说明

> 按键编号范围为 `1` ~ `32`，超出范围会作为 Lua 参数错误抛出。

| 名称 | 编号 |
|---|---:|
| `left` | 1 |
| `right` | 2 |
| `middle` | 3 |
| `back` | 4 |
| `forward` | 5 |

> 编号 1、2、3 通常对应左键、右键和中键；`back`、`forward` 是编号 4、5 的别名。编号 6 ~ 32 没有固定名称，具体行为取决于 iOS 和目标 App。部分 App 可能只能接收到前 5 个按键。


## 示例

```lua
local m = assert(mouse.connect())
assert(m:down("left"))
assert(m:up("left"))
assert(m:down(13))
assert(m:up(13))
assert(m:disconnect())
```

---

Source: [luaiconv 编码转换扩展库](https://xxtouch.app/docs/handbook/open-source/luaiconv.md)
Path: handbook/open-source/luaiconv.md

# luaiconv 编码转换扩展库

[luaiconv 手册地址](https://ittner.github.io/lua-iconv/#api-documentation)

---

## GBK 编码转 UTF-8 编码示例

```lua
local iconv = require("iconv")
local cd = iconv.new("utf-8", "gbk") -- 新建一个 GBK 编码到 UTF8 编码的转换器
local f = io.open("/var/mobile/1.txt", "rb")
local s = f:read("*a")
f:close()
sys.alert(cd:iconv(s))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## Unicode Little Endian (UTF-16LE)  编码转 UTF-8 编码示例

```lua
local iconv = require("iconv")
local cd = iconv.new("utf-8", "utf-16le") -- 新建一个 UTF-16LE 编码到 UTF8 编码的转换器
local f = io.open("/var/mobile/1.txt", "rb")
local s = f:read("*a")
f:close()
sys.alert(cd:iconv(s))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

## Unicode Big Endian (UTF-16BE)  编码转 UTF-8 编码示例

```lua
local iconv = require("iconv")
local cd = iconv.new("utf-8", "utf-16be") -- 新建一个 UTF-16BE 编码到 UTF8 编码的转换器
local f = io.open("/var/mobile/1.txt", "rb")
local s = f:read("*a")
f:close()
sys.alert(cd:iconv(s))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取剪贴板中的数据 (pasteboard.read)](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.read.md)
Path: handbook/pasteboard/pasteboard.read.md

# 获取剪贴板中的数据 (pasteboard.read)


## 声明

```lua
数据 = pasteboard.read([ 通用类型标识 ])
```


## 参数

- 通用类型标识
    文本型，可选参数，[Uniform Type Identifiers](https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html)，默认 自动判断格式
    存在 **通用类型标识** 参数的情况下，会强制以该 **通用类型标识** 格式读取剪贴板中数据，若是剪贴板中数据无法以该 **通用类型标识** 读取，则返回空字符串


## 返回值

- 数据
    字符串型，返回剪贴板中的数据，可能是文本，也可能是二进制数据。若无法以该方式读取，则返回 `""`（空文本）


## 说明

> 从系统剪贴板中读取内容
> 关键词：读取剪贴板、获取剪贴板、读取剪切板、获取剪切板


## 示例

```lua
sys.alert("剪贴板中的内容："..pasteboard.read())
--
sys.alert("剪贴板中的内容："..pasteboard.read('public.text')) -- 富文本也强行以文本方式读取剪贴板
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [读取属性表数据 (plist.load)](https://xxtouch.app/docs/handbook/plist/plist.load.md)
Path: handbook/plist/plist.load.md

# 读取属性表数据 (plist.load)


## 声明

```lua
关联表 = plist.load(属性表数据)
```


## 参数

- 属性表数据
    字符串型，需要读取的属性表数据

## 返回值

- 关联表
    表型 或 nil，加载成功则返回属性表数据的树形结构对应的一个表，否则返回 nil


## 说明

> plist.dump 的反函数，将属性表数据转换成表
> 非通用数据类型值不支持读取，会被忽略


## 示例

```lua
-- 示例 1
local jtmp = plist.load([[
{
    arr = (
        46,
        99,
        7,
    );
    dict = {
        a = 55;
        b = 65;
        c = 9;
    };
}
]])
sys.alert(jtmp.arr[1]) -- 输出 46
sys.alert(jtmp.dict.c) -- 输出 9
--
-- 示例 2
local xtmp = plist.load([[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>arr</key>
    <array>
        <string>46</string>
        <string>99</string>
        <string>7</string>
    </array>
    <key>dict</key>
    <dict>
        <key>a</key>
        <string>55</string>
        <key>b</key>
        <string>65</string>
        <key>c</key>
        <string>9</string>
    </dict>
</dict>
</plist>
]])
sys.alert(xtmp.arr[1]) -- 输出 46
sys.alert(xtmp.dict.c) -- 输出 9
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [向进程队列词典中压入一个值 (proc_queue_push)](https://xxtouch.app/docs/handbook/proc/proc_queue_push.md)
Path: handbook/proc/proc_queue_push.md

# 向进程队列词典中压入一个值 (proc_queue_push)


## 声明

```lua
尺寸 = proc_queue_push(键, 值)
```


## 参数

- 键
    字符串型，代表键
- 值
    字符串型，代表需要压入的值

## 返回值

- 尺寸
    整数型，压入值之后，返回该队列的尺寸，如果返回 0 ，则为压入失败


## 说明

> **此函数效果等同 [proc_queue_push_back](/docs/handbook/proc/proc_queue_push_back.md)**
> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> **进程队列词典的队列尺寸不能大于 10000，尺寸超过的队列将丢弃最先压入的值**
> 往进程队列词典中压入一个值，压入值之后，返回该队列的尺寸
> 不能压入空字符串


## 示例

```lua
local size = proc_queue_push("billnos", "name")
if size ~= 0 then
    print("has "..size.." bill(s)")
else
    print("failed")
end
```

---

Source: [保持屏幕 (screen.keep)](https://xxtouch.app/docs/handbook/screen/screen.keep.md)
Path: handbook/screen/screen.keep.md

# 保持屏幕 (screen.keep)


## 声明

```lua
screen.keep()
```


## 说明

> 在脚本中保持当前屏幕内容到缓冲区，多次调用取色、找色、截图、找图等函数时，将从保持的缓冲区中获取内容，而不会从实际屏幕获取图像，从而提升图色判断的性能。
> 该函数为优化类函数，能够为大量的静态图像处理函数提供性能优化。
> 调用仅会影响 XXTouch 截图取色函数的数据源，**不会** 导致屏幕实际画面卡住不动。


## 示例

```lua
-- 循环取 6144 个点的颜色输出到日志
t = {}
screen.keep()
for k = 1, 640, 10 do
    for j = 1, 960, 10 do
        --格式化为十六进制文本
        t[#t + 1] = string.format("%X", screen.get_color(k, j))
    end
end
screen.unkeep()
nLog(t)
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)


## 小知识

> - 针对同一位置两行连续单独的 screen.get_color 调用可能取到不同的值
> - 不使用 screen.keep 的情况下 screen.get_color 单独调用耗时约等于一次 screen.keep 的耗时
> - 调用 screen.keep 之后，再连续调用 50 次 screen.get_color 耗时约等于调用一次 screen.keep

---

Source: [脚本守护模式是什么？](https://xxtouch.app/docs/handbook/supplement/daemon-mode.md)
Path: handbook/supplement/daemon-mode.md

# 脚本守护模式是什么？


- 脚本守护模式保证脚本在被外力因素（如服务程序崩溃、设备断电）终止后，设备恢复正常状态时能够自动重新启动脚本。以下情形除外：
  - 设备断电后未再充电
  - 设备无法开机
  - 设备重启后丢失越狱状态
  - 设备处于安全模式
  - 设备设有锁屏密码并重启
  - 用户主动终止
  - 脚本因运行期错误终止
- 守护模式的优先级高于开机启动脚本。因此，在脚本开头加入以下代码，可确保设备故障重启后屏幕已解锁再开始执行：
  ```lua
  while (device.is_screen_locked()) do
    device.unlock_screen()
    sys.msleep(1000)
  end
  sys.toast("屏幕已解锁，脚本开始")
  -- 以下为正式脚本逻辑
  -- ...
  ```

---

Source: [弹出输入提示 (sys.input_box)](https://xxtouch.app/docs/handbook/sys/sys.input_box.md)
Path: handbook/sys/sys.input_box.md

# 弹出输入提示 (sys.input_box)


## 说明

> 弹出一个系统输入对话框，最多可以有 3 个按钮，2 个文本框，阻塞所有线程等待返回
> 标题默认为 `"脚本提示"`
> **20260108 以后版本该函数将在多任务环境让出**


## 示例

```lua
输入的内容 = sys.input_box("描述内容")
--
输入的内容 = sys.input_box("标题", "这是描述内容")
--
输入的内容 = sys.input_box("标题", "这是描述内容", 0)
--
输入的内容 = sys.input_box("标题", "描述内容", "文本框阴影提示", 0)
--
输入的内容 = sys.input_box("标题", "描述内容", "文本框阴影提示", "文本框里面的内容", 0)
--
输入的内容 = sys.input_box("标题", "描述内容", "文本框阴影提示", "文本框里面的内容", "默认按钮标题", 0)
--
输入的内容, 做出的选择 = sys.input_box("标题", "描述内容", "文本框阴影提示", "文本框里面的内容", "默认按钮标题", "按钮1标题", 0)
--
输入的内容, 做出的选择 = sys.input_box("标题", "描述内容", "文本框阴影提示", "文本框里面的内容", "默认按钮标题", "按钮1标题", "按钮2标题", 0)
--
输入的内容1, 输入的内容2 = sys.input_box("标题", "描述内容", {"文本框1阴影提示", "文本框2阴影提示"}, 0)
--
输入的内容1, 输入的内容2 = sys.input_box("标题", "描述内容", {"文本框1阴影提示", "文本框2阴影提示"}, {"文本框1里面的内容", "文本框2里面的内容"}, 0)
--
输入的内容1, 输入的内容2, 做出的选择 = sys.input_box("标题", "描述内容", {"文本框1阴影提示", "文本框2阴影提示"}, {"文本框1里面的内容", "文本框2里面的内容"}, "默认按钮标题", "按钮1标题", "按钮2标题", 0)
```

---

Source: [HID 事件消息](https://xxtouch.app/docs/handbook/system-callback/hid.md)
Path: handbook/system-callback/hid.md

# HID 事件消息


## 声明

```lua
thread.register_event("xxtouch.hid_event", function(val)
    local event = json.decode(val)
    if event.event_type=="touch" then
        if event.event_name=="touch.on" then
            sys.toast("触摸接触位置: ("..event.x..", "..event.y..")\n"..event.time)
        elseif event.event_name=="touch.move" then
            sys.toast("触摸移动到位置: ("..event.x..", "..event.y..")\n"..event.time)
        elseif event.event_name=="touch.off" then
            sys.toast("触摸从位置: ("..event.x..", "..event.y..") 离开屏幕\n"..event.time)
        end
    else
        if event.event_name=="key.down" then
            sys.toast("按下按键: "..event.key_name.."\n"..event.time)
        elseif event.event_name=="key.up" then
            sys.toast("抬起按键: "..event.key_name.."\n"..event.time)
        end
    end
end)
```


## 状态

- val
    - 注册监听后，所有 HID 事件信息都会传递到此回调。由于严重影响脚本运行效率，不再需要时请及时反注册
    - HID 事件中所有触摸坐标均以竖屏 HOME 键在下为初始坐标系。若需转换，可使用 [screen.rotate_xy](/docs/handbook/screen/screen.rotate_xy.md)


## 示例

```lua
-- 清空消息队列
proc_queue_clear("xxtouch.hid_event")
--
-- 建立监听回调
local eid = thread.register_event("xxtouch.hid_event", function(val)
    local event = json.decode(val)
    if event.event_type=="touch" then
        if event.event_name=="touch.on" then
            sys.toast("触摸接触位置: ("..event.x..", "..event.y..")\n"..event.time)
        elseif event.event_name=="touch.move" then
            sys.toast("触摸移动到位置: ("..event.x..", "..event.y..")\n"..event.time)
        elseif event.event_name=="touch.off" then
            sys.toast("触摸从位置: ("..event.x..", "..event.y..") 离开屏幕\n"..event.time)
        end
    else
        if event.event_name=="key.down" then
            sys.toast("按下按键: "..event.key_name.."\n"..event.time)
        elseif event.event_name=="key.up" then
            sys.toast("抬起按键: "..event.key_name.."\n"..event.time)
        end
    end
end)
--
touch.on(100, 100):off()
sys.msleep(1000)
key.press('homebutton')
--
sys.msleep(20000) -- 等待 20 秒
--
-- 反注册回调函数，如果不反注册监听，那么脚本不会在此结束
thread.unregister_event("xxtouch.hid_event", eid)
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`proc_queue_clear`](/docs/handbook/proc/proc_queue_clear.md)、[`thread.register_event`](/docs/handbook/thread/thread.register_event.md)、[`thread.unregister_event`](/docs/handbook/thread/thread.unregister_event.md)

---

Source: [从队列中移除一项任务 (thread.kill)](https://xxtouch.app/docs/handbook/thread/thread.kill.md)
Path: handbook/thread/thread.kill.md

# 从队列中移除一项任务 (thread.kill)


## 声明

```lua
thread.kill(任务ID)
```


## 参数

- 任务 ID
    整数型


## 说明

> 从队列中移除一项任务，不管它是否已经开始，是否已经完成


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [! 模拟手指在屏幕上移动 (:move)](https://xxtouch.app/docs/handbook/touch/touchm_move.md)
Path: handbook/touch/touchm_move.md

# ! 模拟手指在屏幕上移动 (:move)


## 声明

```lua
触摸事件 = 触摸事件:move(横坐标, 纵坐标)
```


## 参数

- 横坐标, 纵坐标
    整数型，需要移动至的点于当前旋转坐标系的坐标


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 模拟手指从当前位置移动到其它的位置
> 当前方法坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**
> 该函数可同时使用以下方式调用（其中**手指 ID**必须是范围在 1 ~ 29 的任意数字）
```lua
touch.move(手指ID, 横坐标, 纵坐标)
touch.move(手指ID, 横坐标, 纵坐标, 压力值)
```
> 该调用方式与 :move 方法不同之处在于，它是立刻移动到目标位置，不能设置步进


## 示例

```lua
-- 模拟一个手指于点 100, 100 的位置接触屏幕，然后匀速滑动到点 200, 200 的位置，然后松开
touch.on(100, 100):move(200, 200):off()

-- 另外一个用法
touch.on(1, 100, 100) -- 模拟编号为 1 的手指于点 100, 100 的位置接触屏幕
for i=1, 100 do       -- 循环逐步移动编号为 1 的手指到点 100, 200 的位置
    touch.move(1, 100, 100 + i)
end
touch.off(1)          -- 松开编号为 1 的手指
```

---

Source: [通用选项说明](https://xxtouch.app/docs/handbook/ui_element/options.md)
Path: handbook/ui_element/options.md

# 通用选项说明

> **该模块在 20260507 以后版本方可使用**

多个 `ui_element` 接口接受选项表，用于指定目标 App、返回数量、递归深度、命中验证和滚动步进。

## 查询选项

```lua
local options = {
    pid = app.front_pid(),
    max_level = 2,
    max_elements = 200,
    include_hit_state = true,
}
```

- pid
    整数型，指定目标 App 的进程标识符。不传时通常使用前台 App。
- max_level
    整数型，子元素递归深度。常用 `1` 或 `2` 控制返回数据量。
- max_elements
    整数型，最多返回的顶层元素数量。
- fallback_children
    布尔型，普通列表为空时尝试读取子元素。默认值随接口不同而不同。
- include_hit_state
    布尔型，是否补充命中状态字段。
- hit_test
    布尔型，是否启用屏幕采样命中。普通脚本通常不需要开启。
- fallback_hit_test
    布尔型，普通列表为空时是否尝试屏幕采样命中。
- hit_test_spacing
    数值型，屏幕采样间距，单位为逻辑坐标。默认 `40`。

### 属性排除选项 {#attribute-exclusions}

**20261115 起可用**。仅用于 `snapshot()` 和 `list_text_elements()`；均为布尔型，默认 `false`，对子元素同样生效。不需要相应状态时，启用这些排除选项可减少查询开销，加快快照抓取。

- exclude_visibility
    为 `true` 时跳过可见性查询，省略 `isVisible`。
- exclude_map
    为 `true` 时跳过地图属性判断，省略 `isMap`，保留地图元素。
- exclude_hit_state
    为 `true` 时跳过中心点命中检查，省略 `canHit`、`hitVerified`、`hitTestPoint` 和 `hitTestPointLogical`；不能与 `include_hit_state = true` 同时使用。

元素范围、文字和坐标保持不变，`hit_test` / `fallback_hit_test` 的补抓规则不变。需要按这些状态筛选时，不要排除相应字段。

## 动作选项

- point
    表型，指定滚动或命中使用的坐标点，例如 `{ x = 200, y = 700 }`，单位为物理像素。
- x / y
    整数型，和 `point` 等价，可直接放在选项表中。
- steps
    数值型，用于滚动、增加或减少操作的步进参数。具体效果取决于目标控件。

## 说明

> `list_text_elements()` 为兼容旧脚本，默认更保守。
> `find()`、`find_all()`、`snapshot()` 和动作类接口更适合新脚本直接使用。
> `hit_test` 可能返回更接近当前顶层界面的元素，但成本更高，建议只在普通查询拿不到元素时使用。

---

Source: [将文本编码成二维码图片 (utils.qr_encode)](https://xxtouch.app/docs/handbook/utils/utils.qr_encode.md)
Path: handbook/utils/utils.qr_encode.md

# 将文本编码成二维码图片 (utils.qr_encode)


## 声明

```lua
图片 = utils.qr_encode(文本内容[, {
    size = 尺寸,
    fill_color = 填充颜色,
    shadow_color = 阴影颜色,
}])
```


## 参数

- 文本内容
    文本型，需要编码成二维码的文本内容
- 尺寸
    整数型，需要编码成二维码的边长，默认 320
- 填充颜色
    整数型，填充二维码图片的颜色，默认 0xff000000 (黑色不透明)
- 阴影颜色
    整数型，二维码阴影，默认 0x00000000 (完全透明)


## 返回值

- 图片
    图片对象，返回生成的二维码图片对象


## 说明

> 将文本编码成一个指定尺寸背景色透明（0x00000000）的二维码图片


## 示例

- 生成一个尺寸为 320、蓝色填充、背景透明的二维码并保存到相册
```lua
local img = utils.qr_encode("https://www.xxtouch.app", {
    size = 320,
    fill_color = 0xff409bff,
    shadow_color = 0xff308bef,
})
img:save_to_album()
```
**注**：上述代码中使用了非本章函数 [`:save_to_album`](/docs/handbook/image/imagem_save_to_album.md)

- 部分 App（如微信）无法识别透明或深色背景的二维码，可以使用 [`:replace_color`](/docs/handbook/image/imagem_replace_color.md) 将透明背景替换成白色：
```lua
local img = utils.qr_encode("https://www.xxtouch.app", {
    size = 320,
    fill_color = 0xff000000, -- 使用不透明的黑色填充
})
img:replace_color(0x00000000, 0xffffffff) -- 将透明色背景替换成白色
img:save_to_album()
```
**注**：上述代码中使用了非本章函数 [`:replace_color`](/docs/handbook/image/imagem_replace_color.md)、[`:save_to_album`](/docs/handbook/image/imagem_save_to_album.md)

---

Source: [选择一个 VPN 配置 (vpnconf.select)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.select.md)
Path: handbook/vpnconf/vpnconf.select.md

# 选择一个 VPN 配置 (vpnconf.select)


## 声明

```lua
操作成败 = vpnconf.select(显示名或VPNID)
```


## 参数

- 显示名或 VPNID
    文本型，选择一个 VPN，多个同显示名 VPN 不保证选择哪个。如果需要精确选择可传入 VPNID

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false，操作失败通常是因为指定配置不存在


## 说明

> VPNID 可通过 [vpnconf.list](/docs/handbook/vpnconf/vpnconf.list.md) 函数获得


## 示例

```lua
local success = vpnconf.select('DemoVPN')
if success then
    sys.alert('操作成功')
else
    sys.alert('操作失败，请确认要选中的 VPN 配置是否存在')
end
```

---

Source: [在一个 webview 上执行一段 JS (webview.eval)](https://xxtouch.app/docs/handbook/webview/webview.eval.md)
Path: handbook/webview/webview.eval.md

# 在一个 webview 上执行一段 JS (webview.eval)


## 声明

```lua
str = webview.eval(js [, id ])
```


## 参数

- js
    文本型，需要执行的 JS 代码
- id
    整数型，可选参数，表示当前 webview 的 id，范围 1 ~ 1000，默认为 1


## 返回值

- str
    文本型，返回执行 JS 代码产生的返回值


## 说明

> 在一个 webview 上执行一段 JS 并获得返回值文字


## 示例

```lua
r = webview.eval("a = 3; b = 2; a * b;")
```

---

Source: [获取当前脚本包中的资源路径 (xpp.resource_path)](https://xxtouch.app/docs/handbook/xpp/xpp.resource_path.md)
Path: handbook/xpp/xpp.resource_path.md

# 获取当前脚本包中的资源路径 (xpp.resource_path)


## 声明

```lua
资源路径 = xpp.resource_path(资源文件名)
```


## 参数

- 资源文件名
    文本型，需要获取的资源文件名

## 返回值

- 资源路径
    文本型 或 nil，返回当前脚本包的某个资源文件的路径，如果资源不存在，则返回 nil


## 说明

> 用于从运行着的脚本中获取当前脚本包中某个资源文件的路径，支持本地化
> 脚本包标准参考 [XPP](/docs/XPP/index.md)


## 示例

```lua
local path = xpp.resource_path('appicon.png')
```

---

Source: [展示一个配置界面 (xui.show)](https://xxtouch.app/docs/handbook/xui/xui.show.md)
Path: handbook/xui/xui.show.md

# 展示一个配置界面 (xui.show)


## 声明

```lua
xui.show(配置界面文件名)
```


## 参数

- 配置界面文件名
    文本型，需要展示的当前脚本包中的配置界面文件（.xui）的文件名，只能是当前脚本包内的配置界面文件（.xui）


## 说明

> 立刻调起 App 展示指定的配置界面
> 该函数不会阻塞，没有返回值；展示失败的错误信息会在 App 内显示
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.show('interface.xui')
```

---

Source: [获取 App 的插件信息 (app.plugin_info)](https://xxtouch.app/docs/handbook/app/app.plugin_info.md)
Path: handbook/app/app.plugin_info.md

# 获取 App 的插件信息 (app.plugin_info)


## 声明

```lua
插件信息 = app.plugin_info(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 插件信息
    表型，返回应用程序的插件信息，格式为 `{{bid = "xxx", bundle_path = "xxx", data_path = "xxx"}, ...}`。若不存在则返回空表


## 示例

```lua
local info = app.plugin_info("com.tencent.mqq") -- 获得 QQ 的插件信息
nLog(info)
```

---

Source: [清理系统缓存 (clear.caches)](https://xxtouch.app/docs/handbook/clear/clear.caches.md)
Path: handbook/clear/clear.caches.md

# 清理系统缓存 (clear.caches)


## 声明

```lua
clear.caches()
```


## 说明

> 清理系统缓存。执行期间系统会明显卡顿，且此时所有线程均被阻塞
> 该函数耗时可能会非常长；执行过程中强行停止脚本将导致停止缓慢（被强制终止）


## 示例

```lua
clear.caches()
--
clear.caches{no_uicache = true} -- 支持不使用 uicache 清理，uicache 耗时很长，可使用 os.execute('su mobile -c uicache') 来代替
```

---

Source: [脚本被终止时执行一些代码的方法](https://xxtouch.app/docs/handbook/control-flow/terminate-callback.md)
Path: handbook/control-flow/terminate-callback.md

# 脚本被终止时执行一些代码的方法


## 说明

> 这不是一个具体的函数，而是利用 Lua 垃圾回收机制在脚本结束 (或被终止) 时执行一些代码的约定写法
> > **原理**：定义一个全局对象 (表型值)，将其 **终结器** (finalizer) 设为一个函数；当 Lua 虚拟机结束时，所有 Lua 对象（也包括你定义的这个）的 **终结器** 都会被调用。Lua 中的 **终结器** 即对象的 [__gc 元方法](https://cloudwu.github.io/lua53doc/manual.html#2.4)


## 简易示例

```lua
-- 关键词 脚本终止回调 脚本结束回调
随便取个变量名 = {}
setmetatable(随便取个变量名, {
    __gc = function(...)
        sys.toast('被终止了！')
        sys.msleep(500)
    end
})
--
while (true) do
    sys.toast("现在可尝试手动结束脚本\n\n"..os.date("%Y-%m-%d %H:%M:%S"))
    sys.msleep(1000)
end
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[setmetatable](https://cloudwu.github.io/lua53doc/manual.html#pdf-setmetatable)


## 完整封装示例

```lua
function atexit(callback) -- 参数为一个函数，使用 atexit(一个函数) 注册一个函数在脚本结束时执行，建议不要耗时太长
    ____atexit_guard____ = ____atexit_guard____ or {}
    if type(____atexit_guard____) == 'table' then
        if not getmetatable(____atexit_guard____) then
            setmetatable(____atexit_guard____, {
                __gc = function(self)
                    if type(self.callback) == 'function' then
                        pcall(self.callback)
                    end
                end
            })
        end
        ____atexit_guard____.callback = callback
    else
        error('别用 `____atexit_guard____` 命名你的变量。')
    end
end
-- 以上代码可拷贝到你的脚本的开头，以下为使用示例
--
-- 使用 atexit 注册一个终止回调函数
atexit(function()
    sys.toast('被终止了！')
    sys.msleep(500)
end)
--
while (true) do
    sys.toast("现在可尝试手动结束脚本\n\n"..os.date("%Y-%m-%d %H:%M:%S"))
    sys.msleep(1000)
end
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[setmetatable](https://cloudwu.github.io/lua53doc/manual.html#pdf-setmetatable)

---

Source: [创建一个通用 CoreML 推理器 (coreml.new_model_request)](https://xxtouch.app/docs/handbook/coreml/coreml.new_model_request.md)
Path: handbook/coreml/coreml.new_model_request.md

# 创建一个通用 CoreML 推理器 (coreml.new_model_request)

`coreml.new_model_request` 用于加载一个已经编译好的 CoreML 模型，并创建一个不依赖 Vision 的通用推理器。
它适合文本模型、张量输入模型、多输入多输出模型、Embedding 模型以及任何“输入不是一张普通图片”的模型。

如果模型本身是图片识别流程，且希望直接传 `image` 对象做视觉推理，应优先使用 `new_vision_request`。
如果需要自己准备输入特征，或模型输入包含 `MLMultiArray`、文本 token、多个命名输入，应使用该接口。

另外，`coreml.session(...)` 是这个函数的别名。

## 声明

```lua
通用推理器对象, 错误信息 = coreml.new_model_request(编译好的模型路径)
```

或

```lua
通用推理器对象, 错误信息 = coreml.new_model_request({
    compiled_model_path = 编译好的模型路径,
    uses_cpu_only = 是否只使用 CPU,
    compute_units = 计算单元配置,
})
```

## 参数

- `compiled_model_path`
    文本型，已经编译完成的 `.mlmodelc` 模型目录路径。

- `uses_cpu_only`
    布尔型，可选参数，是否默认只使用 CPU 推理，默认 `false`。

- `compute_units`
    文本型，可选参数，**iOS 12+** 生效。支持以下值：
    - `"all"`
    - `"cpu_only"` 或 `"cpu"`
    - `"cpu_and_gpu"` 或 `"gpu"`
    - `"cpu_and_neural_engine"`、`"ane"` 或 `"neural_engine"`（**iOS 16+**）

    当 `uses_cpu_only = true` 时，会优先强制使用 CPUOnly 配置。

## 返回值

- 通用推理器对象
    通用推理器对象，创建失败返回 `nil`。

- 错误信息
    文本型，创建成功返回 `nil`，失败时返回错误信息。

## 说明

> **该函数在 20260319 以后版本方可使用**

- 基础能力支持 **iOS 11+**
- `compute_units` 相关配置依赖 **iOS 12+**
- 如果模型声明的是 image feature，且你想把 `image_object` 直接作为输入传给这个通用 request，则需要 **iOS 13+**
- 传入输入参数时，需使用“输入名映射表”的形式，例如 `{ input_ids = ids }`
- 输入值支持数字、字符串、布尔值、字典、`MLMultiArray`，以及模型声明为图片特征时的 `image` 对象
- 这个对象只负责模型推理，不负责图片预处理或文本分词；这些步骤需要在 Lua 层自行准备
- 同一个推理器对象可以重复调用 `predict()` / `run()`，适合缓存起来反复使用，而不是每次推理都重新创建
- 如果老设备或某些模型在默认后端上不稳定，可以在创建时设置 `uses_cpu_only = true`

## 类型判断

### 声明

```lua
是否通用推理器 = coreml.is_model_request(需要判断的值)
```

或

```lua
是否通用推理器 = coreml.is_session(需要判断的值)
```

### 参数

- 需要判断的值
    值，需要判断是否为 CoreML 通用推理器对象的值。

### 返回值

- 是否通用推理器
    布尔型，是返回 `true`，否则返回 `false`。

### 说明

- `coreml.is_session()` 与 `coreml.is_model_request()` 是同义接口
- 适合在通用 Lua 封装里做类型保护或参数校验
- 如果你已经明确持有的是 `new_model_request(...)` / `session(...)` 返回值，通常不需要额外调用它

## 示例

```lua
local compiled_model_path = XXT_HOME_PATH.."/models/demo_text.mlmodelc"

local req, err = coreml.new_model_request({
    compiled_model_path = compiled_model_path,
    uses_cpu_only = false,
    compute_units = "all",
})
if not req then
    error(err)
end

local out = assert(req:predict({
    input_ids = ids,
}))

print(req:input_names())
print(req:output_names())
print(out[1])
```

---

Source: [获取系统根路径对应的越狱根路径 (jbroot)](https://xxtouch.app/docs/handbook/develop-helper/jbroot.md)
Path: handbook/develop-helper/jbroot.md

# 获取系统根路径对应的越狱根路径 (jbroot)


## 声明

```lua
越狱根路径 = jbroot(系统根路径)
```

## 参数

- 系统根路径
    文本型，系统根下的路径

## 返回值

- 越狱根路径
    文本型，参数 `系统根路径` 对应的 `越狱根路径`

## 说明

> 在 roothide 及 rootless 版 XXTouch 中，该函数将系统根下的路径映射为越狱根下同名路径的绝对路径
> 在 rootful 或巨魔版 XXTouch 中，该函数直接原样返回传入参数
> **软件版本在 1.3.8 或以上方可使用**

## 示例

```lua
nLog(jbroot('/')) -- /var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/
```

---

Source: [获取屏幕锁定状态 (device.is_screen_locked)](https://xxtouch.app/docs/handbook/device/device.is_screen_locked.md)
Path: handbook/device/device.is_screen_locked.md

# 获取屏幕锁定状态 (device.is_screen_locked)


## 声明

```lua
是否锁屏 = device.is_screen_locked()
```


## 返回值

- 是否锁屏
    布尔型，返回是否已经锁定屏幕


## 说明

> 判断是否已经锁定屏幕


## 示例

```lua
if device.is_screen_locked() then
    -- 屏幕已锁定
else
    -- 屏幕是解锁状态
end
```

---

Source: [配置对话框的标题 (:set_title)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_title.md)
Path: handbook/dialog/dialogm_set_title.md

# 配置对话框的标题 (:set_title)


## 声明

```lua
对话框对象 = 对话框对象:set_title(标题文本)
```


## 参数

- 标题文本
    文本型，对话框的标题

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 配置对话框的标题


## 示例

```lua
dialog():set_title('标题'):show()
```

---

Source: [读取一个文件中的所有数据 (file.reads)](https://xxtouch.app/docs/handbook/file/file.reads.md)
Path: handbook/file/file.reads.md

# 读取一个文件中的所有数据 (file.reads)


## 声明

```lua
内容, 错误信息 = file.reads(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- 内容
    字符串型 或 nil，文件不存在返回 nil，否则返回整个文件的数据
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 读取一个文件中的所有数据


## 示例

```lua
local data, err = file.reads("/var/mobile/1.zip")
if data then
    sys.alert("`/var/mobile/1.zip` 的尺寸为："..#data.."字节")
else
    sys.alert("读取失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [! 按一下手柄按键 (:press)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_press.md)
Path: handbook/gamepad/gamepadm_press.md

# ! 按一下手柄按键 (:press)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:press(按键 [, 按下时间 ])
```

## 参数

- 按键
    整数型 或 文本型，支持的编号和名称见 [按键参数说明](gamepadm_down.md)
- 按下时间
    非负有限数值，可选参数，按键保持按下的毫秒数，默认为 60

## 返回值

- 状态
    布尔型，按下并松开按键成功返回 true，设备断开、忙、目标按键已经按下或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

- 只按下并松开目标按键，不会改变其他已经按下的按键
- 目标按键已经处于按下状态时调用失败
- `press` 等待按下时间时会让出当前 Lua 执行线程；在此期间，同一手柄上的其他操作返回 `false, "hardware gamepad is busy"`，不同手柄对象仍可独立操作
- 参数类型错误、未知名称和越界值会作为 Lua 参数错误抛出

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:press("a"))
assert(pad:press("menu"))
assert(pad:press(32))
assert(pad:disconnect())
```

---

Source: [HTTP 文件下载 (http.download)](https://xxtouch.app/docs/handbook/http/http.download.md)
Path: handbook/http/http.download.md

# HTTP 文件下载 (http.download)


## 声明

```lua
下载成败, 下载信息 = http.download(URL, 本地文件路径 [, 连接超时秒, 断点续传模式, 分块回调函数, 缓冲区尺寸 ])
```


## 参数

- URL
    文本型，远端文件地址
- 本地文件路径
    文本型，需要保存到的本地路径
- 连接超时秒
    实数型，可选参数，连接超时时间，单位秒，默认 10
- 断点续传模式
    布尔型，可选参数，是否需要支持断点续传，是为 true，否为 false，默认 false
- 分块回调函数
    函数型，可选参数，分块回调函数，每下载完一个分块都会回调一次该函数，默认 空函数
    分块回调函数第一个参数为当前下载的信息，回调函数返回 true 则打断这次下载
- 缓冲区尺寸
    整数型，可选参数，缓冲区大小字节数，默认自动最优配置

## 返回值

- 下载成败
    布尔型，连接是否成功
- 下载信息
    表型 或 文本型，如果连接成功则返回表型下载信息，否则返回连接失败原因文本描述


## 说明

```lua
-- 第二个返回值下载信息结构如下
{
    resource_size = 远端资源总字节数,
    start_pos = 本次下载从资源的开始的位置,
    size_download = 本次下载的字节数,
    speed_download = 本次下载的速度 (单位：字节/秒) ,
}
```
> 该函数适合大文件下载，在传输的过程中停止脚本可能会缓慢
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 简单示例

```lua
local done, info = http.download("https://192.168.31.13/1.zip", "/var/mobile/1.zip")
if (done) then
    sys.alert("下载完成")
else
    sys.alert("连接失败："..info)
end
```


## 复杂示例

```lua
local done, info = http.download("https://192.168.31.13/1.zip", "/var/mobile/1.zip", 10, true, function(binfo)
    local percent = math.floor(((binfo.start_pos + binfo.size_download) / binfo.resource_size) * 100)
    sys.toast("下载进度 "..percent.."%")
end, 4096 * 1024)
--
if (done) then
    if (info.start_pos + info.size_download < info.resource_size) then
        sys.alert(
            "下载中断\n本次下载 "..info.size_download.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始下载"
            .."\n平均速度为 "..math.floor(info.speed_download/1024).." kB/s"
            .."\n还有剩 "..(info.resource_size - (info.start_pos + info.size_download)).." 字节"
        )
    else
        sys.alert(
            "下载完成\n本次下载 "..info.size_download.." 字节"
            .."\n从第 "..info.start_pos.." 字节开始下载"
            .."\n平均速度为 "..math.floor(info.speed_download/1024).." kB/s"
        )
    end
else
    sys.alert("连接失败："..info)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)

## 错误信息参考

**Requested range was not delivered by the server** 这个错误表示服务器可能不支持断点续传，将断点续传选项设为 false 即可

---

Source: [新建一个文本图片对象 (image.new_text_image)](https://xxtouch.app/docs/handbook/image/image.new_text_image.md)
Path: handbook/image/image.new_text_image.md

# 新建一个文本图片对象 (image.new_text_image)


## 声明

```lua
图片 = image.new_text_image(文本[, {
   font = 字体,
   size = 字体大小,
   color = 字体颜色,
   alpha = 字体不透明度,
   back_color = 背景色,
   back_alpha = 背景不透明度,
}])
```


## 参数

- 文本
    文本型，需要绘制的文本内容
- 字体
    文本型，可选参数，需要绘制的文本的字体，默认 "Arial"
- 字体大小
    实数型，可选参数，需要绘制的文本的字体大小，默认 20.0
- 字体颜色
    整数型，可选参数，需要绘制的文本的字体颜色，默认 0xffffff (白)
- 字体不透明度
    整数型，可选参数，需要绘制的文本的字体不透明度，范围 0~255，默认 255
- 背景色
    整数型，可选参数，图片背景色，默认 0x000000 (黑)
- 背景不透明度
    整数型，可选参数，图片背景不透明度，范围 0~255，默认 255


## 返回值

- 图片
    图片对象，返回新建的图片对象


## 说明

> 新建一个适合尺寸的图片对象，并将文本绘制于上
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用

---

Source: [JSON 中的 NULL 常量 (json.null)](https://xxtouch.app/docs/handbook/json/json.null.md)
Path: handbook/json/json.null.md

# JSON 中的 NULL 常量 (json.null)


## 声明

```lua
json.null
```


## 说明

> 这不是一个函数，是一个常量。以文本形式打印为 “`userdata: 0x0`”
> 它用于表示 json 中对应的 null 值
> **为什么它有必要存在：** Lua table 中的 nil 会被视为不存在，转换为 JSON 后对应的 key 会消失，因此需要一个特定值来表示 null
> 该值可在 XUI 中使用


## 示例

```lua
local tb = json.decode('{"nullvalue":null}')
if tb['nullvalue'] == json.null then
    sys.alert(json.null)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [! 模拟键入文本 (key.send_text)](https://xxtouch.app/docs/handbook/key/key.send_text.md)
Path: handbook/key/key.send_text.md

# ! 模拟键入文本 (key.send_text)

> **本页所述硬件键盘功能在 20260805 以后版本方可使用**

## 声明

```lua
key.send_text(文本 [, 每键延迟, Shift 键延迟])
```

## 参数

- 文本
    文本型，待输入的文字，只能是英文、数字、空格、半角字符以及 `"\b"`、`"\r"`、`"\t"`。
- 每键延迟
    整数型，每次按键之间的延迟，单位为毫秒；默认没有延迟，以设备性能极限输入。
- Shift 键延迟
    整数型，单位为毫秒；大写字母或某些特殊符号需要按住 Shift 输入，例如 `@` 是 `Shift + 2`。

## 说明

> 该函数可用于 `sys.input_text` 无效时，强制模拟键盘键入。

- 连接[全局硬件键盘](key.connect_global_keyboard.md)后，文本会通过该对象输入；没有全局硬件键盘时，仍保持原有行为。
- 硬件键盘根据当前 Lua 的美式键盘映射生成按键和 Shift 组合，最终字符仍受目标系统键盘布局影响。
- 通过硬件键盘输入时，会保护调用前已经按下的按键；发送失败时不会自动改用原有输入方式重试。

## 示例

```lua
key.send_text("AbC12#") -- 尽可能快地键入文本
--
key.send_text("AbC12#", 300) -- 每键入一次延迟 0.3 秒
```

---

Source: [松开硬件鼠标按键 (:up)](https://xxtouch.app/docs/handbook/mouse/mousem_up.md)
Path: handbook/mouse/mousem_up.md

# 松开硬件鼠标按键 (:up)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:up(按键)
```


## 参数

- 按键
    整数型或文本型，可传入 `1` ~ `32`，或预定义的按键名称；详见 [`:down` 的按键说明](mousem_down.md)


## 返回值

- 状态
    布尔型，松开成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，松开失败的原因


## 说明

> 松开指定的硬件鼠标按键。


## 示例

```lua
local m = assert(mouse.connect())
assert(m:down("left"))
assert(m:up("left"))
assert(m:down(13))
assert(m:up(13))
assert(m:disconnect())
```

---

Source: [lpeg 扩展库](https://xxtouch.app/docs/handbook/open-source/lpeg.md)
Path: handbook/open-source/lpeg.md

# lpeg 扩展库

[lpeg 手册地址](https://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html)

---

---

Source: [清空剪贴板 (pasteboard.clear)](https://xxtouch.app/docs/handbook/pasteboard/pasteboard.clear.md)
Path: handbook/pasteboard/pasteboard.clear.md

# 清空剪贴板 (pasteboard.clear)


## 声明

```lua
剪贴板中的数据 = pasteboard.clear()
```


## 返回值

- 剪贴板中的数据
    表型，返回剪贴板中的数据，可能包含多项，每项包含 `type` 和 `data` 两个字段

    <details>

    <summary>剪贴板中的数据结构</summary>

    ```lua
    {
        {
            type = "public.utf8-plain-text",
            data = "具体的数据",
        },
        {
            type = "public.rtf",
            data = "具体的数据",
        },
        {
            type = "public.html",
            data = "具体的数据",
        },
        ...
    }
    ```

    </details>

## 说明

> 清空系统剪贴板
> 关键词：清空剪贴板、清空剪切板、清空粘贴板
> **软件版本在 1.3.8 或以上方可使用**

## 示例

```lua
pasteboard.clear() -- 清空剪贴板
```

---

Source: [取 Lua 表的属性表数据 (plist.dump)](https://xxtouch.app/docs/handbook/plist/plist.dump.md)
Path: handbook/plist/plist.dump.md

# 取 Lua 表的属性表数据 (plist.dump)


## 声明

```lua
属性表数据 = plist.dump(关联表[, 属性表数据格式])
```


## 参数

- 关联表
    表型，需要转换成属性表数据的 Lua 表
- 属性表数据格式
    文本型，可选参数，只能是 "binary" 或者 "XML"，以及 "openstep"，默认为 "XML"

## 返回值

- 属性表数据
    字符串型 或 nil，转换成功返回数据内容，转换失败返回 nil


## 说明

> plist.load 的反函数，将表转换成属性表数据


## 示例

```lua
local tab = {
    arr = {
        46,
        99,
        7,
    };
    dict = {
        a = 55;
        b = 65;
        c = 9;
    };
}
--
local xplist = plist.dump(tab)
sys.alert(xplist) -- 输出 XML 格式的属性表数据
--
local bplist = plist.dump(tab, "binary")
sys.alert(bplist) -- 二进制格式的属性表数据，打印出来会乱码
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从进程队列词典中弹出一个值 (proc_queue_pop)](https://xxtouch.app/docs/handbook/proc/proc_queue_pop.md)
Path: handbook/proc/proc_queue_pop.md

# 从进程队列词典中弹出一个值 (proc_queue_pop)


## 声明

```lua
值 = proc_queue_pop(键)
```


## 参数

- 键
    字符串型

## 返回值

- 值
    字符串型，返回弹出的值，如果队列不存在或为空，则返回空字符串


## 说明

> **此函数效果等同 [proc_queue_pop_front](/docs/handbook/proc/proc_queue_pop_front.md)**
> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> 从进程队列词典中弹出一个值
> 如果队列不存在或为空，则弹出一个空字符串


## 示例

```lua
local billno = proc_queue_pop("billnos")
if billno ~= "" then
    print(billno)
else
    print("no bill")
end
```

---

Source: [取消保持屏幕 (screen.unkeep)](https://xxtouch.app/docs/handbook/screen/screen.unkeep.md)
Path: handbook/screen/screen.unkeep.md

# 取消保持屏幕 (screen.unkeep)


## 声明

```lua
screen.unkeep()
```


## 说明

> 取消 [screen.keep](/docs/handbook/screen/screen.keep.md) 函数的效果，释放内存中的屏幕图像


## 示例

参考 [`screen.keep` 中的示例](/docs/handbook/screen/screen.keep.md)

---

Source: [开机启动的时机说明](https://xxtouch.app/docs/handbook/supplement/bootstrap.md)
Path: handbook/supplement/bootstrap.md

# 开机启动的时机说明


- 开机启动脚本需要主屏幕完全准备就绪后才会运作，一般会在开机后延迟片刻再启动。
- 常见的开机不启动情形：
  - 无法进入桌面
  - 开机后进入安全模式
  - 设置了锁屏密码

---

Source: [输入文字 (sys.input_text)](https://xxtouch.app/docs/handbook/sys/sys.input_text.md)
Path: handbook/sys/sys.input_text.md

# 输入文字 (sys.input_text)


## 声明

```lua
sys.input_text(文字内容 [, 输入完成按回车 ])
```


## 参数

- 文字内容
    文本型，需要输入的文字，**20250625 支持** `"\b"` (退格键)
- 输入完成按回车
    布尔型，是否在输入完毕后按下键盘上的回车键 (发送、搜索等) ，默认 false


## 说明

> 在前台程序的可以输入文本的地方输入文字
> 该函数原理为先将文本写入剪贴板，然后调用粘贴快捷键 (**command \+ v**) 粘贴文本
> **该函数的调用会影响公共剪贴板，请注意在调用之前备份好剪贴板中的重要数据**
> **在系统公共剪贴板损坏的情况下，该函数的文字输入会失效。即如果设备无法正常复制粘贴文字，则该函数也无法使用**
> **与此函数已知的冲突插件：Background Manager**
> 如果遇到无法作用的情况可以参考 [`key.send_text`](/docs/handbook/key/key.send_text.md) 或许能解决


## 示例

```lua
sys.input_text("hello") -- 在当前光标所在的文本框输入 "hello"
--
sys.input_text("hello", true) -- 在聊天/搜索类输入框中输入 "hello" 并按下回车键以触发发送或搜索
```

---

Source: [阻塞等待另一个任务完成 (thread.wait)](https://xxtouch.app/docs/handbook/thread/thread.wait.md)
Path: handbook/thread/thread.wait.md

# 阻塞等待另一个任务完成 (thread.wait)


## 声明

```lua
thread.wait(任务ID, 超时时间秒)
```


## 参数

- 任务 ID
    整数型
- 超时时间秒
    实数型，等待超时时间，超时后将返回，单位：秒


## 说明

> 当前线程阻塞等待另一个任务完成


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [! 模拟手指在屏幕上施加压力 (:press)](https://xxtouch.app/docs/handbook/touch/touchm_press.md)
Path: handbook/touch/touchm_press.md

# ! 模拟手指在屏幕上施加压力 (:press)


## 声明

```lua
触摸事件 = 触摸事件:press([ 压力, 速度 ])
```


## 参数

- 压力
    整数型，可选参数，压力，范围 1~10000，默认 1000
- 速度
    整数型，可选参数，施加压力的速度，范围 1~100，默认 最快速


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 模拟手指在当前位置施加压力，该方法仅能用于支持 3D Touch 的设备
> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 示例

```lua
touch.on(100, 100):press():off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，施加默认压力后松开

touch.on(100, 100):press(2000):off() -- 同上，但压力值改为 2000

touch.on(100, 100):press(2000, 50):off() -- 同上，并将施加压力的速度降低
```

---

Source: [ui_element 使用示例](https://xxtouch.app/docs/handbook/ui_element/samples.md)
Path: handbook/ui_element/samples.md

# ui_element 使用示例

> **该模块在 20260507 以后版本方可使用**

## 查找并点击按钮

```lua
local ui_element = require("ui_element")

local ok, info_or_err = ui_element.click({
    title = "继续",
    role = "button",
})

if not ok then
    sys.toast(info_or_err)
end
```

## 查找搜索框并输入文本

```lua
local ui_element = require("ui_element")

local search, err = ui_element.find({
    title = "搜索",
    role = "text_field",
})

if search then
    ui_element.set_text(search, "XXTouch")
else
    sys.toast(err)
end
```

## 读取当前页面上的文本

```lua
local ui_element = require("ui_element")

local list, err = ui_element.list_text_elements({
    max_level = 1,
})

if list then
    for _, item in ipairs(list) do
        if item.text then
            nLog(item.text)
        end
    end
else
    sys.toast(err)
end
```

## 滚动当前页面

```lua
local ui_element = require("ui_element")

ui_element.scroll("down", {
    point = { x = 200, y = 700 },
})
```

## 切换开关

```lua
local ui_element = require("ui_element")

ui_element.set_checked({
    title = "飞行模式",
    role = "switch",
}, false)
```

## 复用一次快照

```lua
local ui_element = require("ui_element")

local ui, err = ui_element.snapshot({
    max_level = 2,
})

if ui then
    local item = ui:find({ text_contains = "隐私" })
    if item then
        ui:click(item)
    end
else
    sys.toast(err)
end
```

## 调节滑块或滚轮

```lua
local ui_element = require("ui_element")

ui_element.increase({
    role = "slider",
    index = 1,
})

ui_element.decrease({
    role = "picker",
    index = 1,
}, {
    steps = 2,
})
```

**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [获得当前脚本的启动参数 (utils.launch_args)](https://xxtouch.app/docs/handbook/utils/utils.launch_args.md)
Path: handbook/utils/utils.launch_args.md

# 获得当前脚本的启动参数 (utils.launch_args)


## 声明

```lua
启动参数关联表 = utils.launch_args()
```


## 返回值

- 启动参数关联表
    表型，返回一个用于描述当次启动的参数表，结构可以自行用 [table.deep_dump](/docs/handbook/ext-table/table.deep_dump.md) 打印查看


## 说明

> 获得当前脚本的启动参数，推荐配合 [Activator](https://cydia.saurik.com/package/libactivator/) 激活脚本


## 示例

```lua
sys.alert(table.deep_dump(utils.launch_args()))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`table.deep_dump`](/docs/handbook/ext-table/table.deep_dump.md)
```lua
-- 获取当前脚本文件路径 (注：不是任何情况下脚本都有一个文件路径)
sys.alert("当前的脚本路径是："..tostring(utils.launch_args().path))
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[tostring](https://cloudwu.github.io/lua53doc/manual.html#pdf-tostring)

---

Source: [删除一个 VPN 配置 (vpnconf.delete)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.delete.md)
Path: handbook/vpnconf/vpnconf.delete.md

# 删除一个 VPN 配置 (vpnconf.delete)


## 声明

```lua
操作成败 = vpnconf.delete(显示名或VPNID)
```


## 参数

- 显示名或 VPNID
    文本型，删除一个 VPN，多个同显示名 VPN 不保证删除哪个。如果需要精确删除可传入 VPNID


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false，操作失败通常是因为指定配置不存在


## 说明

> VPNID 可通过 [vpnconf.list](/docs/handbook/vpnconf/vpnconf.list.md) 函数获得


## 示例

```lua
local success = vpnconf.delete('DemoVPN')
if success then
    sys.alert('操作成功')
else
    sys.alert('操作失败，请确认要删除的 VPN 配置是否存在')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 遍历删除所有 VPN 配置示例

```lua
-- 关键词：删除所有 VPN、批量删除 VPN
local vpnlist = vpnconf.list()
if vpnlist then
    for _,v in ipairs(vpnlist) do
        if (vpnconf.delete(v.VPNID)) then
            sys.log('成功删除：'..v.dispName..'('..v.VPNID..')')
        else
            sys.log('无法删除：'..v.dispName..'('..v.VPNID..')')
        end
    end
    sys.alert('操作完成！')
else
    sys.alert('获取 VPN 列表失败')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.log`](/docs/handbook/sys/sys.log.md)

---

Source: [获取一个 webview 的区域及层级信息 (webview.frame)](https://xxtouch.app/docs/handbook/webview/webview.frame.md)
Path: handbook/webview/webview.frame.md

# 获取一个 webview 的区域及层级信息 (webview.frame)


## 声明

```lua
frame = webview.frame([ id ])
```


## 参数

- id
    整数型，可选参数，表示当前 webview 的 id，范围 1 ~ 1000，默认为 1

## 返回值

- frame
    表型，返回当前 webview 的区域及层级信息


## 说明

> 获取一个 webview 的区域及层级信息


## 示例

```lua
local frame = webview.frame(1)
sys.alert(
    "位置为:".."("..frame.x..","..frame.y..")\n"..
    "大小为:".."(宽:"..frame.width..",高:"..frame.height..")\n"..
    "层级为:".."("..frame.level..")"
)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [收起正在展示的配置界面 (xui.dismiss)](https://xxtouch.app/docs/handbook/xui/xui.dismiss.md)
Path: handbook/xui/xui.dismiss.md

# 收起正在展示的配置界面 (xui.dismiss)


## 声明

```lua
xui.dismiss()
```


## 说明

> 尝试让 App 收起配置界面并返回主界面
> 该函数不会阻塞，无返回值。若当前没有配置界面正在展示，则仅跳转到 App，不执行其他操作
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.dismiss()
```

---

Source: [弹出一个应用通知 (app.pop_banner)](https://xxtouch.app/docs/handbook/app/app.pop_banner.md)
Path: handbook/app/app.pop_banner.md

# 弹出一个应用通知 (app.pop_banner)


## 声明

```lua
app.pop_banner(应用包标识符, 标题, 内容)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
- 标题
    文本型，通知的标题
- 内容
    文本型，通知的内容


## 说明

> **需要完整越狱环境，并在 Cydia 或者 Sileo 安装基础依赖 “libbulletin” 方可使用**


## 示例

```lua
app.pop_banner('com.tencent.mqq', 'QQ', '您有一条新消息')
```

---

Source: [清除相册中所有本地照片 (clear.all_photos)](https://xxtouch.app/docs/handbook/clear/clear.all_photos.md)
Path: handbook/clear/clear.all_photos.md

# 清除相册中所有本地照片 (clear.all_photos)


## 声明

```lua
clear.all_photos()
```


## 说明

> 清除相册中所有本地照片，不会影响 iCloud 照片流
> 该函数耗时可能会非常长；执行过程中强行停止脚本将导致停止缓慢（被强制终止）
> **警告：该函数调用的效果不可逆**


## 示例

```lua
clear.all_photos()
```

---

Source: [CoreML 通用推理器对象方法](https://xxtouch.app/docs/handbook/coreml/coreml_model_request_object_methods.md)
Path: handbook/coreml/coreml_model_request_object_methods.md

# CoreML 通用推理器对象方法

`coreml_model_request_object` 是 `coreml.new_model_request(...)` / `coreml.session(...)` 返回的推理对象。
它负责把准备好的输入特征送进模型，并返回按输出名组织的结果。

这个对象的职责很单一：

- 提交推理
- 读取异步结果
- 查询模型输入输出签名
- 查询当前 request 的运行配置

它不负责文本分词、图片预处理或业务后处理，这些应由 Lua 层自行组织。

> **这些方法在 20260319 以后版本方可使用**

## 推理方法

### `:predict(inputs[, opts])`

```lua
返回结果, 错误信息 = 通用推理器对象:predict(输入映射表)
```

或

```lua
是否已提交, 错误信息 = 通用推理器对象:predict(输入映射表, {
    async = 是否异步,
    multi_array_output = "table" 或 "MLMultiArray",
    uses_cpu_only = 是否本次只使用 CPU,
})
```

执行一次单样本模型推理。

- `inputs` 必须是按输入名组织的表
- 同步模式下直接返回结果表
- 异步模式下只返回 `true`，稍后再用 `:is_done()` 和 `:results()` 取结果
- `multi_array_output` 用于控制模型输出里的 `MLMultiArray` 是保留为原生张量，还是转成 Lua 表
- `uses_cpu_only` 只影响本次推理，不会修改对象默认配置

### `:run(inputs[, opts])`

`run()` 是 `predict()` 的别名，行为完全一致。

### `:predict_batch(batch_inputs[, opts])`

```lua
批量结果, 错误信息 = 通用推理器对象:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})
```

执行 batch 推理。**需要 iOS 12+**。

- `batch_inputs` 必须是数组，数组里的每一项都是一个“按输入名组织的输入表”
- 同步模式下返回 batch 结果数组；每个元素仍按单样本输出规则组织
- 异步模式下返回 `true`，稍后通过 `:results()` 取回
- `opts` 字段与 `predict()` 相同

### `:run_batch(batch_inputs[, opts])`

`run_batch()` 是 `predict_batch()` 的别名，行为完全一致。

### `:results([opts])`

```lua
返回结果, 错误信息 = 通用推理器对象:results()
```

或

```lua
返回结果, 错误信息 = 通用推理器对象:results({
    multi_array_output = "table" 或 "MLMultiArray",
})
```

读取最近一次异步推理的结果。

- 如果最近一次异步调用来自 `predict()`，这里返回单样本结果表
- 如果最近一次异步调用来自 `predict_batch()`，这里返回 batch 结果数组
- `multi_array_output` 默认沿用最近一次推理调用的设置
- 如果异步任务还没结束，返回 `nil, "not yet"`
- 如果当前没有可读取的成功结果，返回 `nil, "unknown"`

### `:is_done()`

```lua
是否完成 = 通用推理器对象:is_done()
```

检查最近一次异步推理是否已经完成。只有在 `predict(..., { async = true })` 或 `predict_batch(..., { async = true })` 之后才有意义。

## 运行配置与元信息

### `:metadata()`

```lua
元信息 = 通用推理器对象:metadata()
```

返回模型自带的 metadata。适合调试、通用封装或做模型信息展示。

### `:uses_cpu_only()`

```lua
是否默认只用 CPU = 通用推理器对象:uses_cpu_only()
```

返回这个 request 创建时保存的默认 CPUOnly 配置。

### `:compute_units()`

```lua
计算单元配置 = 通用推理器对象:compute_units()
```

返回这个 request 当前记录的 `compute_units` 字符串。

- 在 **iOS 12+** 上，这里返回创建时记录下来的小写字符串
- 常见返回值包括 `"all"`、`"cpu_only"`、`"cpu"`、`"cpu_and_gpu"`、`"gpu"`、`"cpu_and_neural_engine"`、`"ane"`、`"neural_engine"`
- 如果创建时传了 `uses_cpu_only = true`，这里会返回 `"cpu_only"`
- 在 **iOS 11** 上返回 `nil`

## 输入输出签名方法

### `:input_count()` / `:output_count()`

返回输入 / 输出特征数量。

### `:input_features()` / `:output_features()`

返回按名称索引的特征描述表。

当前实际返回字段比较精简：

- `type`
- `optional`
- 当特征类型是 `multi_array` 时，额外带 `shape` 和 `data_type`

### `:input_info(name_or_index)` / `:output_info(name_or_index)`

按输入 / 输出名或 1-based 序号读取单个特征的信息。

- 返回字段与 `input_features()` / `output_features()` 基本一致
- 会额外带 `name`
- 序号访问使用与 `input_names()` / `output_names()` 相同的排序规则

### `:input_names()` / `:output_names()`

返回稳定有序的输入 / 输出名列表。

- 名字会按字典序排序
- `output_names()` 的顺序与同步推理返回结果里的数字索引顺序一致

### `:class_labels()`

返回模型声明的类别标签。**需要 iOS 14+**。

## 生命周期与类型判断

### `:close()`

销毁底层 request 状态。关闭后不应再继续调用其它方法。

### `:is_model_request()` / `:is_session()`

对象级类型判断接口，二者是同义别名。

## 说明

- `predict()` / `run()` 的返回结果始终是一个表
- 结果同时支持数字索引和输出名索引
- `predict_batch()` / `run_batch()` 返回的是 batch 结果数组；数组里的每项仍是“数字索引 + 输出名索引”双访问方式
- 对新的通用推理器来说，`MLMultiArray` 默认保留为原生张量对象，更适合继续做后处理
- 如果只是想看数据内容，或要兼容旧式脚本，可以显式传 `multi_array_output = "table"`

结果访问示例：

```lua
out[1]
out.text_features
batch_out[1].text_features
```

## 示例

```lua
local req = assert(coreml.new_model_request(XXT_HOME_PATH.."/models/demo.mlmodelc"))

local out = assert(req:predict({
    input_ids = ids,
}, {
    multi_array_output = "MLMultiArray",
}))

print(out[1])
print(out.text_features)
print(req:output_names())
```

---

Source: [获取越狱根对应的系统根路径 (rootfs)](https://xxtouch.app/docs/handbook/develop-helper/rootfs.md)
Path: handbook/develop-helper/rootfs.md

# 获取越狱根对应的系统根路径 (rootfs)


## 声明

```lua
系统根路径 = rootfs(越狱根路径)
```

## 参数

- 越狱根路径
    文本型，越狱根下的路径

## 返回值

- 系统根路径
    文本型，参数 `越狱根路径` 对应的 `系统根路径`

## 说明

> 在 roothide 及 rootless 版 XXTouch 中，该函数将越狱根下的路径反向还原为对应的系统根路径（即 `jbroot` 的逆运算）
> 在 rootful 或巨魔版 XXTouch 中，该函数直接原样返回传入参数
> **软件版本在 1.3.8 或以上方可使用**

## 示例

```lua
nLog(rootfs('/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/')) -- /
```

---

Source: [获取前台应用的画面方向 (device.front_orien)](https://xxtouch.app/docs/handbook/device/device.front_orien.md)
Path: handbook/device/device.front_orien.md

# 获取前台应用的画面方向 (device.front_orien)


## 声明

```lua
旋转状态 = device.front_orien()
```


## 返回值

- 旋转状态
    整数型，前台应用画面的旋转方向标识：
    `0`　home 在下（竖屏正向）
    `1`　home 在右（横屏）
    `2`　home 在左（横屏）
    `3`　home 在上（竖屏倒置）
    `4`　获取失败


## 示例

```lua
sys.toast('这个提示会以前台应用的旋转方向显示', device.front_orien())
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [配置对话框的尺寸 (:set_size)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_size.md)
Path: handbook/dialog/dialogm_set_size.md

# 配置对话框的尺寸 (:set_size)


## 声明

```lua
对话框对象 = 对话框对象:set_size(宽度, 高度)
```

## 参数

- 宽度, 高度
    整数型，对话框对象宽高。若不设置，默认为全屏宽高

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 设置对话框的尺寸，如果对话框不是全屏，则会居中于屏幕，并使用半径为 10 的圆角
> 该方法仅在使用 webview 引擎的 dialog 上有效


## 示例

```lua
local dlg = dialog()
dlg:set_size(600, 800)
dlg:show()
```

---

Source: [将数据覆盖写入到文件 (file.writes)](https://xxtouch.app/docs/handbook/file/file.writes.md)
Path: handbook/file/file.writes.md

# 将数据覆盖写入到文件 (file.writes)


## 声明

```lua
写入成败, 错误信息 = file.writes(文件路径, 待写入内容)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 待写入内容
    字符串型，需要写入的数据

## 返回值

- 写入成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将数据覆盖写入到文件，文件不存在会创建文件，目录不存在会返回 false


## 示例

```lua
local success, err = file.writes("/var/mobile/1.txt", "苟")
if success then
    sys.alert("写入成功")
else
    sys.alert("写入失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [设置手柄摇杆位置 (:set_stick)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_set_stick.md)
Path: handbook/gamepad/gamepadm_set_stick.md

# 设置手柄摇杆位置 (:set_stick)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:set_stick(摇杆, x, y)
```

## 参数

- 摇杆
    文本型，可传 `"left"` 或 `"right"`，字符串不区分大小写
- x
    数值型，范围为 `[-1, 1]` 的有限数字；正数向右，负数向左
- y
    数值型，范围为 `[-1, 1]` 的有限数字；正数向上，负数向下

## 返回值

- 状态
    布尔型，摇杆位置设置成功返回 true，设备断开、忙或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

- `0, 0` 表示摇杆回中
- 摇杆位置会直接变为 `(x, y)`，不会自动生成平滑移动过程
- 参数类型错误、未知摇杆名称、非有限数字或越界值会作为 Lua 参数错误抛出

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:set_stick("left", 0.5, 1))
assert(pad:set_stick("left", 0, 0))
assert(pad:disconnect())
```

---

Source: [发起 HEAD 请求 (http.head)](https://xxtouch.app/docs/handbook/http/http.head.md)
Path: handbook/http/http.head.md

# 发起 HEAD 请求 (http.head)


## 声明

```lua
HTTP状态码, 返回头JSON文本 = http.head(URL [, 超时秒, 请求头, URL不ESCAPE ])
```

## 声明（命名参数）

**20250625 支持，20260402 以后版本支持进度参数**
```lua
HTTP状态码, 返回头JSON文本 = http.head{
    url = URL;
    timeout = 超时秒;
    headers = 请求头;
    params = Query参数;
    progress = 进度回调函数;
    progress_interval_ms = 进度回调间隔毫秒;
}
```


## 参数

- URL
    文本型，需要请求的 URL 地址，该方法默认会对 URL 进行 escape 处理，如不需要可参考 **URL 不 ESCAPE** 参数说明
- 超时秒
    实数型，可选参数，请求超时时间，单位秒，默认 10
- 请求头
    表型，可选参数，发出的请求的头部信息，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- Query 参数
    表型，可选参数，发出的请求的 Query 参数，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 进度回调函数
    函数型，可选参数，**20260402 以后版本支持**。请求进度变化时调用，回调函数第一个参数为当前进度信息
- 进度回调间隔毫秒
    整数型，可选参数，**20260402 以后版本支持**。控制进度回调触发间隔，单位毫秒
- **URL 不 ESCAPE**
    布尔型，可选参数，true 表示不对 URL 进行 escape 直接请求，默认 false
    对 URL 进行自定义 escape 可参考 [lcurl 模块](/docs/handbook/open-source/lcurl.md) 的 [easy:escape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:escape)、[easy:unescape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:unescape)


## 返回值

- HTTP 状态码
    整数型，返回当次请求的 http 状态码，请求超时返回 -1
- 返回头 JSON 文本
    文本型 或 nil，请求完成返回的 JSON 形式头部信息，请求超时返回 nil


## 说明

> 使用 HTTP/1.1 协议的 HEAD 方法请求获取网络资源的头部信息
> HEAD 协议通常和 GET 请求会获得同样的返回头，但 HEAD 请求不会返回实际主体内容
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**

进度回调函数接收的 `info` 结构如下：

```lua
{
    count_of_bytes_sent = 已发送字节数;
    count_of_bytes_expected_to_send = 预计需要发送字节数;
    count_of_bytes_received = 已接收字节数;
    count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
```


## 示例

```lua
local c, h = http.head("https://www.xxtouch.app/测试文本.txt")
if c==200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(h) -- 输出请求到的头信息
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从文件创建图片对象 (image.load_file)](https://xxtouch.app/docs/handbook/image/image.load_file.md)
Path: handbook/image/image.load_file.md

# 从文件创建图片对象 (image.load_file)


## 声明

```lua
图片 = image.load_file(文件路径)
```


## 参数

- 文件路径
    文本型，图片文件绝对路径


## 返回值

- 图片
    图片对象 或 nil，返回新建的图片对象，如果文件不存在则返回 nil


## 说明

> 从文件创建图片对象
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用


## 示例

参考 [`:save_to_album` 中"将图片文件转存到相册"的示例](/docs/handbook/image/imagem_save_to_album.md)

---

Source: [输入文字 (key.input_text)](https://xxtouch.app/docs/handbook/key/key.input_text.md)
Path: handbook/key/key.input_text.md

# 输入文字 (key.input_text)

> **该函数在 20260816 以后版本方可使用**

## 声明

```lua
成功, 错误信息 = key.input_text(文字内容 [, 输入完成按回车 ])
```

## 参数

- 文字内容
    文本型，需要输入的 UTF-8 文字，可以为空；其中的 `"\b"` 会执行退格操作
- 输入完成按回车
    布尔型，是否在输入完毕后按下键盘上的回车键，默认 false

## 返回值

- 成功
    布尔型，成功发出模拟输入操作时返回 `true`，失败时返回 `false`
- 错误信息
    文本型，失败时返回错误原因

## 说明

> 通过模拟输入法选字的方式，在前台程序中已经获得焦点的输入框输入文字
>
> 该函数不会读取或修改系统公共剪贴板
>
> **该函数无法在密码输入框中输入文字；密码输入框请使用 [`sys.input_text`](/docs/handbook/sys/sys.input_text.md)**
>
> 返回 `true` 仅表示模拟输入操作已经发出，不表示目标输入框一定接受了文字

## 示例

```lua
local ok, err = key.input_text("你好，XXTouch 🙂")
assert(ok, err)
--
local ok, err = key.input_text("hello!\b", true)
assert(ok, err)
```

---

Source: [示例及支持的键码列表](https://xxtouch.app/docs/handbook/key/samples.md)
Path: handbook/key/samples.md

# 示例及支持的键码列表

## 模拟按 HOME 键

```lua
key.press("HOMEBUTTON")
```

## 模拟长按 HOME 键

```lua
key.down("HOMEBUTTON") -- 按下 HOME 键
sys.msleep(1000) -- 等待 1 秒
key.up("HOMEBUTTON") -- 松开 HOME 键
```

## 模拟双击 HOME 键

```lua
key.press("HOMEBUTTON")
key.press("HOMEBUTTON")
```

## 模拟按锁屏键 (电源键)

```lua
key.press("LOCK")
```

## 模拟按回车键

```lua
key.press("RETURN")
```

## 其它模拟

```lua
-- 下面这个例子是模拟组合键 [command + v] 粘贴剪贴板的文本 (不是 windows 上的 control + v )
key.down("LEFTCOMMAND") -- 按下 command 键
sys.msleep(30) -- 等待 30 毫秒
key.press("V") -- 按一下 v 键
sys.msleep(30) -- 等待 30 毫秒
key.up("LEFTCOMMAND") -- 松开 command 键
--
-- 下面这个例子是模拟组合键 command + `[` 返回上一页
key.down("LEFTCOMMAND") -- 按下 command 键
sys.msleep(30) -- 等待 30 毫秒
key.press("[") -- 按一下 `[` 键
sys.msleep(30) -- 等待 30 毫秒
key.up("LEFTCOMMAND") -- 松开 command 键
--
-- 下面这个例子是 [command + a] 全选然后退格键删除
key.down('LEFTCOMMAND')
sys.msleep(30) -- 等待 30 毫秒
key.press('A') -- 按一下 `A` 键
sys.msleep(30) -- 等待 30 毫秒
key.up('LEFTCOMMAND')
sys.msleep(100) -- 等待 100 毫秒
key.press('BACKSPACE') -- 按一下退格键
--
--
key.press("VOLUMEUP") -- 按一下音量 + 键
key.press("VOLUMEDOWN") -- 按一下音量 - 键
--
key.down("VOLUMEUP") -- 按下音量 + 键
sys.msleep(1000) -- 等待 1 秒
key.up("VOLUMEUP") -- 松开音量 + 键
--
key.down("LOCK") -- 按下锁屏键 (电源键)
sys.msleep(3000) -- 等待 3 秒
key.up("LOCK") -- 松开锁屏键 (电源键)
--
key.press("SHOW_HIDE_KEYBOARD") -- 按一下[隐藏/显示键盘键]隐藏虚拟键盘
--
key.press("SHOW_HIDE_KEYBOARD") -- 再按一下[隐藏/显示键盘键]显示虚拟键盘
--
-- 下面这个例子是模拟组合键 [锁屏键 + HOME键] 实现截屏到相册
key.down("LOCK") -- 按下锁屏键 (电源键)
sys.msleep(100) -- 等待 100 毫秒
key.press("HOMEBUTTON") -- 按一下 HOME 键
sys.msleep(100) -- 等待 100 毫秒
key.up("LOCK") -- 松开锁屏键 (电源键)
--
-- iOS7、iOS8 切换输入法的组合键
key.down("LEFTCOMMAND")
sys.msleep(50)
key.press(" ")
sys.msleep(50)
key.up("LEFTCOMMAND")
--
-- iOS9 切换输入法的组合键
key.down("LEFTCONTROL")
sys.msleep(50)
key.press("SPACE")
sys.msleep(50)
key.up("LEFTCONTROL")
```
**注**：上述代码中使用了非本章函数 [`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

## 支持的键码列表

```lua
-- 字母键：
"A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z"
--
-- 数字键：
"1" "2" "3" "4" "5" "6" "7" "8" "9" "0"
--
-- 功能键：
"F1" "F2" "F3" "F4" "F5" "F6" "F7" "F8" "F9" "F10" "F11" "F12"
--
-- 其它键：
"RETURN"        --< 回车键
"ESCAPE"        --< ESC键
"BACKSPACE"     --< 退格键
"TAB"           --< 制表符键
"SPACE"         --< 空格键
"HYPHEN"        --< "-" 或 "_" 键
"EQUAL"         --< "=" 或 "+" 键
"BRACKETOPEN"   --< "[" 或 "{" 键
"BRACKETCLOSE"  --< "]" 或 "}" 键
"BACKSLASH"     --< "\" 或 "|" 键
"SEMICOLON"     --< ";" 或 ":" 键
"QUOTATION"     --< 单引号或双引号键
"ACCENT"        --< "`" 或 "~" 键
"COMMA"         --< "," 或 "<" 键
"DOT"           --< "." 或 ">" 键
"SLASH"         --< "/" 或 "?" 键
"CAPSLOCK"      --< 大小写锁定键
"PAUSE"
"INSERT"
"HOME"          --< 这个不完全等于 iOS 设备的 HOME 键
"PAGEUP"
"DELETE"
"END"
"PAGEDOWN"
"RIGHTARROW"    --< 向右箭头键
"LEFTARROW"     --< 向左箭头键
"DOWNARROW"     --< 向下箭头键
"UPARROW"       --< 向上箭头键
"LEFTCONTROL"   --< 左侧 Ctrl 键
"LEFTSHIFT"     --< 左侧 Shift 键
"LEFTALT"       --< 左侧 Alt 键
"LEFTCOMMAND"   --< 左侧 Command 键
"RIGHTCONTROL"  --< 右侧 Ctrl 键
"RIGHTSHIFT"    --< 右侧 Shift 键
"RIGHTALT"      --< 右侧 Alt 键
"RIGHTCOMMAND"  --< 右侧 Command 键
"LOCK"          --< 锁屏键，或电源键
"HOMEBUTTON"    --< 这个才等于 iOS 设备的 HOME 键
"FORWARD"       --< 多媒体下一首
"REWIND"        --< 多媒体上一首
"FORWARD2"      --< 多媒体下一首（备用键位）
"REWIND2"       --< 多媒体上一首（备用键位）
"EJECT"
"PLAYPAUSE"     --< 多媒体暂停键
"MUTE"          --< 静音键
"VOLUMEUP"      --< 音量 + 键
"VOLUMEDOWN"    --< 音量 - 键
"SPOTLIGHT"     --< Spotlight 键
"BRIGHTUP"      --< 屏幕亮度 + 键
"BRIGHTDOWN"    --< 屏幕亮度 - 键
"SHOW_HIDE_KEYBOARD" --< 隐藏/显示键盘键
```

---

Source: [! 点击硬件鼠标按键 (:click)](https://xxtouch.app/docs/handbook/mouse/mousem_click.md)
Path: handbook/mouse/mousem_click.md

# ! 点击硬件鼠标按键 (:click)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:click(按键[, 按下毫秒数])
```


## 参数

- 按键
    整数型或文本型，可传入 `1` ~ `32`，或预定义的按键名称；详见 [`:down` 的按键说明](mousem_down.md)
- 按下毫秒数
    非负有限实数，可选参数，按键保持按下的时间，单位为毫秒，默认 60


## 返回值

- 状态
    布尔型，点击成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，点击失败的原因


## 说明

> 按下并松开指定按键，只改变目标按键，不会释放其它已经按下的按键。
> 目标按键已经处于按下状态时，调用会返回失败，避免破坏拖动状态。
> **该方法会在保持按下期间让出当前 Lua 执行线程。让出期间，同一鼠标对象的其它操作会返回 `false, "hardware mouse is busy"`；不同鼠标对象仍可独立操作。**


## 示例

```lua
local m = assert(mouse.connect())
assert(m:click("right"))
assert(m:click(13, 100))
assert(m:click(32))
assert(m:disconnect())
```

---

Source: [LuaFileSystem 扩展库](https://xxtouch.app/docs/handbook/open-source/luafilesystem.md)
Path: handbook/open-source/luafilesystem.md

# LuaFileSystem 扩展库

[LuaFileSystem 手册地址](https://lunarmodules.github.io/luafilesystem/manual.html#reference)

---

## 获取路径中所有文件名示例

```lua
local lfs = require("lfs")
for filename in lfs.dir("/var/mobile") do
    if (filename ~= ".." and filename ~= ".") then
        print(filename)
    end
end
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 获取文件 (夹) 属性示例

```lua
local lfs = require("lfs")
--
local attr = lfs.attributes("/var/mobile")
--
print("类型", attr.mode)
print("最后访问时间", os.date("%Y-%m-%d %H:%M:%S", attr.access))
print("最后修改时间", os.date("%Y-%m-%d %H:%M:%S", attr.modification))
print("最后状态变更时间", os.date("%Y-%m-%d %H:%M:%S", attr.change))
--
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 获取及切换脚本当前目录示例

```lua
local lfs = require 'lfs'
--
sys.alert(lfs.currentdir()) -- 输出 "/"
--
lfs.chdir('/var/mobile/Media/1ferver/lua/scripts')
--
sys.alert(lfs.currentdir()) -- 输出 "/var/mobile/Media/1ferver/lua/scripts"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [属性表数据格式转换 (plist.data_convert)](https://xxtouch.app/docs/handbook/plist/plist.data_convert.md)
Path: handbook/plist/plist.data_convert.md

# 属性表数据格式转换 (plist.data_convert)


## 声明

```lua
转换格式后的属性表数据 = plist.data_convert(属性表数据[, 属性表数据格式])
```


## 参数

- 属性表数据
    字符串型，需要转换的属性表数据
- 属性表数据格式
    文本型，可选参数，只能是 "binary" 或者 "XML"，以及 "openstep"，默认为 "XML"

## 返回值

- 转换格式后的属性表数据
    字符串型 或 nil，转换成功返回数据内容，转换失败返回 nil


## 说明

> plist.data_convert 是纯粹的 plist 格式转换，不涉及 Lua 的序列化和反序列化，转换能保证数据的完整性


## 示例

```lua
local xplist = plist.data_convert(file.reads('/var/mobile/Library/UserNotifications/Library.plist'), "xml")
sys.alert(xplist) -- XML 格式的属性表数据
```
**注**：上述代码中使用了非本章函数 [`file.reads`](/docs/handbook/file/file.reads.md)、[`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从进程队列词典中弹出所有值 (proc_queue_clear)](https://xxtouch.app/docs/handbook/proc/proc_queue_clear.md)
Path: handbook/proc/proc_queue_clear.md

# 从进程队列词典中弹出所有值 (proc_queue_clear)


## 声明

```lua
值集合 = proc_queue_clear(键)
```


## 参数

- 键
    字符串型

## 返回值

- 值集合
    顺序表型，返回包含弹出的所有值的顺序表，如果队列不存在或为空，则返回空表


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> 从进程队列词典中弹出所有值，清空指定队列


## 示例

```lua
local billnos = proc_queue_clear("billnos")
if #billnos ~= 0 then
    for i, billno in ipairs(billnos) do
        print(i, billno)
    end
else
    print("no bill")
end
```

---

Source: [获取屏幕上某点颜色 (screen.get_color)](https://xxtouch.app/docs/handbook/screen/screen.get_color.md)
Path: handbook/screen/screen.get_color.md

# 获取屏幕上某点颜色 (screen.get_color)


## 声明

```lua
颜色值 = screen.get_color(横坐标, 纵坐标)
```

## 参数

- 横坐标, 纵坐标
    整数型，代表目标点的坐标

## 返回值

- 颜色值
    整数型，返回目标点颜色的 RGB 值

## 说明

> 获取屏幕上某个坐标点的颜色
> 当前函数坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响

## 示例

```lua
local c = screen.get_color(512, 133)
if c==0xffffff then
    sys.alert("512, 133 这个点是纯白色")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: ["URL Scheme" 的相关应用](https://xxtouch.app/docs/handbook/supplement/url-scheme.md)
Path: handbook/supplement/url-scheme.md

# "URL Scheme" 的相关应用


具体使用方法参考：[app.open_url](/docs/handbook/app/app.open_url.md)

|URL Scheme|跳转到|
|----|----|
|prefs:root=WIFI|设置-WiFi (或无线局域网) |
|prefs:root=Bluetooth|设置-蓝牙|
|prefs:root=INTERNET_TETHERING|设置-个人热点|
|prefs:root=Wallpaper|设置-墙纸与亮度|
|prefs:root=Sounds|设置-声音|
|prefs:root=Sounds&path=Ringtone|设置-声音-电话铃声|
|prefs:root=Photos|设置-照片与相机|
|prefs:root=STORE|设置-iTunes Store 和 App Store|
|prefs:root=SAFARI|设置-Safari 浏览器|
|prefs:root=SAFARI&path=CLEAR_HISTORY_AND_DATA|设置-Safari 浏览器-清除历史记录与网站数据|
|prefs:root=MUSIC|设置-音乐|
|prefs:root=MUSIC&path=EQ|设置-音乐-均衡器|
|prefs:root=VIDEO|设置-视频|
|prefs:root=NOTES|设置-备忘录|
|prefs:root=Phone|设置-电话|
|prefs:root=CASTLE|设置-iCloud|
|prefs:root=CASTLE&path=STORAGE_AND_BACKUP|设置-iCloud-存储与备份|
|prefs:root=NOTIFICATIONS_ID|设置-通知中心|
|prefs:root=ACCOUNT_SETTINGS|设置-邮件、日历、通讯录|
|prefs:root=LOCATION_SERVICES|设置-定位服务|
|prefs:root=MESSAGES|设置-信息|
|prefs:root=GAMECENTER|设置-Game Center|
|prefs:root=General|设置-通用|
|prefs:root=General&path=About|设置-通用-关于本机|
|prefs:root=General&path=SOFTWARE_UPDATE_LINK|设置-通用-软件更新|
|prefs:root=General&path=ACCESSIBILITY|设置-通用-辅助功能|
|prefs:root=General&path=ACCESSIBILITY/REDUCE_MOTION|设置-通用-辅助功能-减少动态效果|
|prefs:root=General&path=ACCESSIBILITY/ENHANCE_BACKGROUND_CONTRAST|设置-通用-辅助功能-增强对比度|
|prefs:root=General&path=AUTO_CONTENT_DOWNLOAD|设置-通用-后台应用刷新|
|prefs:root=General&path=USAGE|设置-通用-用量|
|prefs:root=General&path=AUTOLOCK|设置-通用-自动锁定|
|prefs:root=General&path=DATE_AND_TIME|设置-通用-日期与时间|
|prefs:root=General&path=Keyboard|设置-通用-键盘|
|prefs:root=General&path=INTERNATIONAL|设置-通用-多语言环境|
|prefs:root=General&path=VPN|设置-通用-VPN|
|prefs:root=General&path=Bluetooth|设置-通用-蓝牙|
|prefs:root=General&path=Network|设置-通用-网络|
|prefs:root=General&path=Network/VPN|设置-通用-网络-VPN|
|prefs:root=General&path=ManagedConfigurationList|设置-通用-描述文件|
|prefs:root=General&path=Reset|设置-通用-还原|

[更多 设置 相关 URL](https://github.com/FifiTheBulldog/ios-settings-urls/blob/master/settings-urls.md)

---

Source: [! 毫秒级延迟 (sys.msleep)](https://xxtouch.app/docs/handbook/sys/sys.msleep.md)
Path: handbook/sys/sys.msleep.md

# ! 毫秒级延迟 (sys.msleep)


## 声明

```lua
sys.msleep(毫秒数)
```


## 参数

- 毫秒数
    实数型，需要延迟等待的时间，单位毫秒


## 说明

> 让当前线程阻塞等待一定时间
> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 示例

```lua
sys.msleep(1000) -- 等待 1 秒
```

---

Source: [注册监听一个事件 (thread.register_event)](https://xxtouch.app/docs/handbook/thread/thread.register_event.md)
Path: handbook/thread/thread.register_event.md

# 注册监听一个事件 (thread.register_event)


## 声明

```lua
事件ID = thread.register_event(事件名, 回调函数 [, 错误回调 ])
```


## 参数

- 事件名
    字符串型，代表事件名
- 回调函数
    函数型，事件将会触发的回调函数
- 错误回调
    函数型，错误回调，当执行任务时发生异常，则会回调这个函数并不再抛出，可选参数，默认在异常时抛出错误

## 返回值

- 事件 ID
    整数型


## 说明

> 注册监听一个事件，当事件名对应的 [进程队列词典](/docs/handbook/proc/proc_queue_push.md) 中有值时，会弹出该值并以该值作为参数触发事件回调


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [模拟手指离开屏幕 (:off)](https://xxtouch.app/docs/handbook/touch/touchm_off.md)
Path: handbook/touch/touchm_off.md

# 模拟手指离开屏幕 (:off)


## 声明

```lua
触摸事件:off([ 横坐标, 纵坐标 ])
```


## 参数

- 横坐标, 纵坐标
    整数型，可选参数，手指离开屏幕的点于当前旋转坐标系的坐标，默认 当前 te 事件记录的坐标


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 模拟手指从当前位置或指定位置离开屏幕，调用后会释放当前触摸事件对象及其占用的手指 id
> 当前方法坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> 该函数可同时使用以下方式调用（其中**手指 ID**必须是范围在 1 ~ 29 的任意数字）
```lua
touch.off(手指ID)
touch.off(手指ID, 横坐标, 纵坐标)
```


## 示例

```lua
touch.on(100, 100):off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后于当前位置离开屏幕

touch.on(100, 100):off(105, 95) -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后于 105, 95 这个位置离开屏幕

-- 另外一个用法
touch.on(1, 100, 100) -- 模拟编号为 1 的手指于点 100, 100 的位置接触屏幕
for i=1, 100 do       -- 循环逐步移动编号为 1 的手指到点 100, 200 的位置
    touch.move(1, 100, 100 + i)
end
touch.off(1)          -- 松开编号为 1 的手指
```

---

Source: [判断当前脚本是否从 App 内启动 (utils.is_launch_via_app)](https://xxtouch.app/docs/handbook/utils/utils.is_launch_via_app.md)
Path: handbook/utils/utils.is_launch_via_app.md

# 判断当前脚本是否从 App 内启动 (utils.is_launch_via_app)


## 声明

```lua
是否从App内启动 = utils.is_launch_via_app()
```


## 返回值

- 是否从 App 内启动
    布尔型，如果当前脚本是从 App 内的启动按钮启动，则返回 true，否则返回 false


## 说明

> 判断当前脚本是否从 App 内的启动按钮启动


## 示例

参考 [`dialog:load`](/docs/handbook/dialog/dialogm_load.md) 中的用法。

---

Source: [以当前选择的 VPN 建立连接 (vpnconf.connect)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.connect.md)
Path: handbook/vpnconf/vpnconf.connect.md

# 以当前选择的 VPN 建立连接 (vpnconf.connect)


## 声明

```lua
操作成败 = vpnconf.connect()
```


## 返回值

- 操作成败
    布尔型，操作成功 (不是连接成功) 返回 true，操作失败返回 false，操作失败通常是因为没有选中的配置


## 示例

```lua
local success = vpnconf.connect()
if success then
    sys.alert('操作成功，正在建立连接……')
else
    sys.alert('当前并无选中任何 VPN 配置，成功创建 VPN 之后，记得调用 vpnconf.select 选中它')
end
```

---

Source: [销毁一个 webview (webview.destroy)](https://xxtouch.app/docs/handbook/webview/webview.destroy.md)
Path: handbook/webview/webview.destroy.md

# 销毁一个 webview (webview.destroy)


## 声明

```lua
webview.destroy([ id ])
```


## 参数

- id
    整数型，可选参数，表示当前 webview 的 id，可使用不同的 id 来同时展现多个 webview，范围 1 ~ 1000，默认为 1


## 说明

> 销毁一个 webview
> 脚本停止时，会自动销毁所有已展示的 webview


## 示例

参考 [本章末尾的综合示例](/docs/handbook/webview/samples.md)

---

Source: [校验配置界面的配置 (xui.setup)](https://xxtouch.app/docs/handbook/xui/xui.setup.md)
Path: handbook/xui/xui.setup.md

# 校验配置界面的配置 (xui.setup)


## 声明

```lua
xui.setup(配置界面文件名)
```


## 参数

- 配置界面文件名
    文本型，需要校验的当前脚本包中的配置界面文件（.xui）的文件名，只能是当前脚本包内的配置界面文件（.xui）


## 说明

> 若配置界面尚未被配置过，则此函数用于生成该配置界面的默认配置；同时会根据配置界面中的控件声明校验并修正已存储配置的值类型
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.setup('interface.xui')
```

---

Source: [运行应用程序 (app.run)](https://xxtouch.app/docs/handbook/app/app.run.md)
Path: handbook/app/app.run.md

# 运行应用程序 (app.run)


## 声明

```lua
状态 = app.run(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 状态
    整数型，返回运行状态
    返回 0 表示启动成功
    返回 其它值 表示启动失败


## 说明

> 如果该函数在您的脚本中无法正常运行，可尝试使用 runApp 函数替代


## 示例

```lua
-- 打开内置天气应用，然后退出
local r = app.run("com.apple.weather") -- 启动应用 包名可在 XXT 应用程序--更多--应用列表 中查看
sys.msleep(10 * 1000) -- 等 10 秒
if r == 0 then
    app.close("com.apple.weather") -- 退出应用
else
    sys.alert("启动失败", 3)
end
```
**注**：上述代码中使用了非本章函数 [`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [清理某个应用的存档数据 (clear.app_data)](https://xxtouch.app/docs/handbook/clear/clear.app_data.md)
Path: handbook/clear/clear.app_data.md

# 清理某个应用的存档数据 (clear.app_data)


## 声明

```lua
是否成功 = clear.app_data(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 是否成功
    布尔型，清理成功返回 true；否则返回 false


## 说明

> 清理应用存档，清理期间所有线程都将阻塞
> 该函数耗时可能会非常长；执行过程中强行停止脚本将导致停止缓慢（被强制终止）
> **警告：该函数调用的效果不可逆**


## 示例

```lua
clear.app_data("com.tencent.xin")
```

---

Source: [获取当前脚本已执行毫秒数 (get_elapsed_ms)](https://xxtouch.app/docs/handbook/develop-helper/get_elapsed_ms.md)
Path: handbook/develop-helper/get_elapsed_ms.md

# 获取当前脚本已执行毫秒数 (get_elapsed_ms)


## 声明

```lua
已执行毫秒数 = get_elapsed_ms()
```


## 返回值

- 已执行毫秒数
    数值型，脚本执行时间，单位为毫秒


## 说明

> 该函数用于获取当前脚本已执行的毫秒数，脚本暂停的时间不计入
> **该函数在 20250511 以后版本方可使用**


## 示例

```lua
local tm = get_elapsed_ms()
sys.msleep(1)
tm = get_elapsed_ms() - tm
nLog('sys.msleep(1) 耗时 '..tm..' ms')
```

---

Source: [锁定设备屏幕旋转 (device.lock_orien)](https://xxtouch.app/docs/handbook/device/device.lock_orien.md)
Path: handbook/device/device.lock_orien.md

# 锁定设备屏幕旋转 (device.lock_orien)


## 声明

```lua
device.lock_orien()
```

## 示例

```lua
device.lock_orien()
```

---

Source: [配置对话框的位置及尺寸 (:set_frame)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_frame.md)
Path: handbook/dialog/dialogm_set_frame.md

# 配置对话框的位置及尺寸 (:set_frame)


## 声明

```lua
对话框对象 = 对话框对象:set_frame(横坐标, 纵坐标, 宽度, 高度)
```


## 参数

- 横坐标, 纵坐标
    整数型，对话框对象左上角位置的横坐标及纵坐标
- 宽度, 高度
    整数型，对话框对象宽高。若不设置，默认为全屏宽高

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 配置对话框的位置及尺寸，使用方角
> 该方法仅在使用 webview 引擎的 dialog 上有效


## 示例

```lua
local dlg = dialog()
dlg:set_frame(0, 0, 600, 800)
dlg:show()
```

---

Source: [将数据追加到文件末尾 (file.appends)](https://xxtouch.app/docs/handbook/file/file.appends.md)
Path: handbook/file/file.appends.md

# 将数据追加到文件末尾 (file.appends)


## 声明

```lua
操作成败, 错误信息 = file.appends(文件路径, 待追加内容)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 待追加内容
    字符串型，需要追加写入的数据


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将数据追加到文件末尾，文件不存在会创建文件，目录不存在会返回 false


## 示例

```lua
local success, err = file.appends("/var/mobile/1.txt", "苟利国家生死以")
if success then
    sys.alert("写入成功")
else
    sys.alert("写入失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [设置手柄方向键状态 (:set_dpad)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_set_dpad.md)
Path: handbook/gamepad/gamepadm_set_dpad.md

# 设置手柄方向键状态 (:set_dpad)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:set_dpad(x, y)
```

## 参数

- x
    整数型，只能为 `-1`、`0` 或 `1`；`1` 表示右，`-1` 表示左
- y
    整数型，只能为 `-1`、`0` 或 `1`；`1` 表示上，`-1` 表示下

## 返回值

- 状态
    布尔型，方向键设置成功返回 true，设备断开、忙或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

- x 和 y 同时非零时表示斜向
- `0, 0` 表示松开方向键
- 参数类型错误和越界值会作为 Lua 参数错误抛出

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:set_dpad(1, 0))   -- 右
assert(pad:set_dpad(-1, 1))  -- 左上
assert(pad:set_dpad(0, 0))   -- 松开
assert(pad:disconnect())
```

---

Source: [发起 DELETE 请求 (http.delete)](https://xxtouch.app/docs/handbook/http/http.delete.md)
Path: handbook/http/http.delete.md

# 发起 DELETE 请求 (http.delete)


## 声明

```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.delete(URL [, 超时秒, 请求头, 请求主体数据, URL不ESCAPE ])
```

## 声明（命名参数）

**20250625 支持，20260402 以后版本支持进度参数**
```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.delete{
    url = URL;
    timeout = 超时秒;
    headers = 请求头;
    params = Query参数;

    -- 以下请求主体参数不可并存，优先顺序为 multipart > data > json > upload_file
    multipart = 请求主体multipart表单;
    data = 请求主体数据;
    json = 请求主体JSON;
    upload_file = 请求主体上传文件路径;

    download_file = 请求成功返回主体保存文件路径;
    progress = 进度回调函数;
    progress_interval_ms = 进度回调间隔毫秒;
}
```


## 参数

- URL
    文本型，需要请求的 URL 地址，该方法默认会对 URL 进行 escape 处理，如不需要可参考 **URL 不 ESCAPE** 参数说明
- 超时秒
    实数型，可选参数，请求超时时间，单位秒，默认 10
- 请求头
    表型，可选参数，发出的请求的头部信息，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- Query 参数
    表型，可选参数，发出的请求的 Query 参数，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体数据
    字符串型，可选参数，使用 DELETE 发送出去的内容，默认为空字符串
    **20250625** 如果为表型，则以 application/x-www-form-urlencoded 的方式编码发送
- 请求主体 multipart 表单
    表型，可选参数，使用 DELETE 发送出去的 multipart 表单数据，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体 JSON
    表型，可选参数，以 application/json 的方式编码发送
- 请求主体上传文件路径
    文本型，可选参数，将文件数据直接作为请求体发送
- 请求成功返回主体保存文件路径
    文本型，可选参数，如果有该参数，则请求成功后返回主体为保存的文件路径
- 进度回调函数
    函数型，可选参数，**20260402 以后版本支持**。请求上传或下载进度变化时调用，回调函数第一个参数为当前进度信息
- 进度回调间隔毫秒
    整数型，可选参数，**20260402 以后版本支持**。控制进度回调触发间隔，单位毫秒
- **URL 不 ESCAPE**
    布尔型，可选参数，true 表示不对 URL 进行 escape 直接请求，默认 false
    对 URL 进行自定义 escape 可参考 [lcurl 模块](/docs/handbook/open-source/lcurl.md) 的 [easy:escape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:escape)、[easy:unescape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:unescape)

## 返回值

- HTTP 状态码
    整数型，返回当次请求的 http 状态码，请求超时返回 -1
- 返回头 JSON 文本
    文本型 或 nil，请求完成返回的 JSON 形式头部信息，请求超时返回 nil
- 返回主体
    字符串型 或 nil，请求完成返回的内容，如果请求主体保存到文件，则此值为文件路径，请求超时返回 nil


## 说明

> 使用 HTTP/1.1 协议的 DELETE 方法请求获取网络资源，它通常用于删除一个网络资源，该协议一般会有权限验证
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**

进度回调函数接收的 `info` 结构如下：

```lua
{
    count_of_bytes_sent = 已发送字节数;
    count_of_bytes_expected_to_send = 预计需要发送字节数;
    count_of_bytes_received = 已接收字节数;
    count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
```


## 示例

```lua
local code, res_headers, body = http.delete("https://httpbin.org/delete?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)", -- 模拟 IE8 的请求
    ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
}, "需要发送过去的数据")
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 示例（命名参数）

```lua
local code, res_headers, body = http.delete{
    url = "https://httpbin.org/delete";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
        ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
    data = "需要发送过去的数据";
}
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从数据创建图片对象 (image.load_data)](https://xxtouch.app/docs/handbook/image/image.load_data.md)
Path: handbook/image/image.load_data.md

# 从数据创建图片对象 (image.load_data)


## 声明

```lua
图片 = image.load_data(图片数据)
```


## 参数

- 图片数据
    字符串型，png 或 jpeg 格式的图片数据


## 返回值

- 图片
    图片对象 或 nil，返回新建的图片对象，如果数据不是图片格式则返回 nil


## 说明

> 从数据创建图片对象
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用


## 示例

参考 [`:save_to_album` 中"从网上下载图片保存到相册"的示例](/docs/handbook/image/imagem_save_to_album.md)

---

Source: [! 创建独立硬件键盘对象 (key.connect_keyboard)](https://xxtouch.app/docs/handbook/key/key.connect_keyboard.md)
Path: handbook/key/key.connect_keyboard.md

# ! 创建独立硬件键盘对象 (key.connect_keyboard)

> **该函数在 20260805 以后版本方可使用**

## 声明

```lua
硬件键盘对象, 错误信息 = key.connect_keyboard([配置属性])
```

## 参数

- 配置属性
    表型，可选参数，用于设置下列常用设备属性；代码块中的值为省略时的默认值：

```lua
{
    VendorID = 0x5858,
    ProductID = 0x0001,
    Product = "XXTouch Keyboard",
    Manufacturer = "XXTouch",
    Transport = "USB",
}
```

还可以设置 `VersionNumber`、`SerialNumber` 和 `LocationID`。其它属性不保证生效。

## 返回值

- 硬件键盘对象
    硬件键盘对象，创建成功时返回；创建失败时返回 `nil`。
- 错误信息
    文本型，创建失败时返回错误信息。

创建失败时，两个返回值合起来为 `nil, error`。

## 说明

> 创建一个独立的硬件键盘对象；每个对象的按键状态和连接生命周期彼此独立。
> 连接等待期间会隐式让出，在函数返回之前，其他[线程](/docs/handbook/thread/index.md)可能获得执行机会。

- `Transport` 只影响 iOS 或目标 App 识别该键盘的方式。设为 `"Bluetooth"` 或 `"BluetoothLowEnergy"` 不会建立蓝牙连接、广播或配对，也不会让键盘出现在其它设备的蓝牙列表中
- 同一时间最多按住 6 个普通按键，修饰键不计入；超过限制时目标系统无法识别具体按键，请先释放部分按键
- 目标 App 可能无法区分多个硬件键盘对象的输入来源
- 本函数只创建独立对象，不会改变现有 `key.*` 接口；如需让现有接口使用硬件键盘，请调用 [`key.connect_global_keyboard`](key.connect_global_keyboard.md)
- 发送失败时不会自动改用其它输入方式重试

## 示例

```lua
local keyboard, err = key.connect_keyboard({
    Product = "XXTouch Keyboard",
})
assert(keyboard, err)

assert(keyboard:press("a"))
assert(keyboard:down("LEFTSHIFT"))
assert(keyboard:press("b"))
assert(keyboard:up("LEFTSHIFT"))
assert(keyboard:send_text("Hello"))

keyboard:disconnect()
```

---

Source: [滚动硬件鼠标滚轮 (:scroll)](https://xxtouch.app/docs/handbook/mouse/mousem_scroll.md)
Path: handbook/mouse/mousem_scroll.md

# 滚动硬件鼠标滚轮 (:scroll)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:scroll(水平滚动量, 垂直滚动量)
```


## 参数

- 水平滚动量
    整数型，滚动步数，范围 `[-127, 127]`；正数向右滚动
- 垂直滚动量
    整数型，滚动步数，范围 `[-127, 127]`；正数向上滚动


## 返回值

- 状态
    布尔型，滚动成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，滚动失败的原因


## 说明

> 滚动量不是像素值，系统与应用可能会根据自身设置缩放实际滚动距离。
> 越界值会作为 Lua 参数错误抛出。


## 示例

```lua
local m = assert(mouse.connect())
assert(m:scroll(0, 10))
assert(m:disconnect())
```

---

Source: [LuaSQLite3 模块](https://xxtouch.app/docs/handbook/open-source/luasqlite3.md)
Path: handbook/open-source/luasqlite3.md

# LuaSQLite3 模块

[LuaSQLite3 手册地址](https://lua.sqlite.org/home/doc/tip/doc/lsqlite3.wiki)

---

## 引用示例

```lua
local sqlite3 = require('sqlite3')
```

## 读取短信示例

```lua
local sqlite3 = require('sqlite3')
--
local db = sqlite3.open('/private/var/mobile/Library/SMS/sms.db')
--
local handle_map = {}
local messages = {}
local APPLE_EPOCH_OFFSET = 978307200
--
db:exec('select handle_id, text, date from message', function (ud, ncols, values, names)
    local date_num = tonumber(values[3])
    if date_num > os.time() * (1000^2) then
        date_num = date_num // (1000^3)
    elseif date_num > os.time() * 1000 then
        date_num = date_num // (1000^2)
    elseif date_num > os.time() * 2 then
        date_num = date_num // 1000
    end
    messages[#messages + 1] = {
        handle_id = values[1],
        text = values[2],
        date = os.date("%Y-%m-%d %H:%M:%S", APPLE_EPOCH_OFFSET + date_num)
    }
    return sqlite3.OK
end)
--
db:exec('select ROWID, id from handle', function (ud, ncols, values, names)
    handle_map[values[1]] = values[2]
    return sqlite3.OK
end)
db:close()
--
for _,v in ipairs(messages) do
    v.id = handle_map[v.handle_id]
    v.handle_id = nil
end
--
local results = {}
for _,v in ipairs(messages) do
    results[#results + 1] = string.format("[%s](%s):%s", v.date, v.id, v.text)
end
--
sys.toast(table.concat(results, '\n'))
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[table.concat](https://cloudwu.github.io/lua53doc/manual.html#pdf-table.concat)

---

Source: [读取进程队列词典中所有的值 (proc_queue_read)](https://xxtouch.app/docs/handbook/proc/proc_queue_read.md)
Path: handbook/proc/proc_queue_read.md

# 读取进程队列词典中所有的值 (proc_queue_read)


## 声明

```lua
值集合 = proc_queue_read(键)
```


## 参数

- 键
    字符串型


## 返回值

- 值集合
    顺序表型，返回包含所有值的顺序表，如果队列不存在或为空，则返回空表


## 说明

> **该函数在 20250106 以后的版本方可使用**
> **所有以 "xxtouch\." 或 "1ferver\." 开头的进程队列词典全部被保留**
> 读取进程队列词典中某个队列所有的值


## 示例

```lua
local billnos = proc_queue_read("billnos")
if #billnos ~= 0 then
    for i, billno in ipairs(billnos) do
        print(i, billno)
    end
else
    print("no bill")
end
```

---

Source: [获取屏幕上某点颜色 RGB (screen.get_color_rgb)](https://xxtouch.app/docs/handbook/screen/screen.get_color_rgb.md)
Path: handbook/screen/screen.get_color_rgb.md

# 获取屏幕上某点颜色 RGB (screen.get_color_rgb)


## 声明

```lua
红, 绿, 蓝 = screen.get_color_rgb(横坐标, 纵坐标)
```

## 参数

- 横坐标, 纵坐标
    整数型，代表目标点的坐标

## 返回值

- 红, 绿, 蓝
    整数型，返回目标点颜色的 `红、绿、蓝` 值，取值范围 0~255

## 说明

> 获取屏幕上某个坐标点的颜色并拆分成 红\(R\) 绿\(G\) 蓝\(B\) 形式
> 当前函数坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响

## 示例

```lua
local r, g, b = screen.get_color_rgb(512, 133)
if r==0xff and g==0xff and b==0xff then
    sys.alert("512, 133 这个点是纯白色")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [日期格式化相关 (os.date)](https://xxtouch.app/docs/handbook/supplement/os.date.md)
Path: handbook/supplement/os.date.md

# 日期格式化相关 (os.date)


[os.date](https://cloudwu.github.io/lua53doc/manual.html#pdf-os.date) 第二个参数是可选参数，默认为当前时间

|格式|示例|描述|结果|
|----|----|----|----|
|%Y-%m-%d %H:%M:%S|os.date\("%Y-%m-%d %H:%M:%S", 1487356783\)|一种常用日期时间格式|2017-02-18 02:39:43|
|%Y-%m-%d|os.date\("%Y-%m-%d", 1487356783\)|一种常用日期格式|2017-02-18|
|%a|os.date\("%a", 1487356783\)|短星期名|Sat|
|%A|os.date\("%A", 1487356783\)|全星期名|Saturday|
|%b|os.date\("%b", 1487356783\)|简写的月份名|Feb|
|%B|os.date\("%B", 1487356783\)|月份的全称|February|
|%c|os.date\("%c", 1487356783\)|标准的日期的时间串|Sat Feb 18 02:39:43 2017|
|%d|os.date\("%d", 1487356783\)|月的天[01-31]|18|
|%H|os.date\("%H", 1487356783\)|24小时制的时[00-23]|02|
|%I|os.date\("%I", 1487356783\)|12小时制的时[01-12]|02|
|%j|os.date\("%j", 1487356783\)|年的天[001-366]|049|
|%M|os.date\("%M", 1487356783\)|分钟[00-59]|39|
|%m|os.date\("%m", 1487356783\)|月份[01-12]|02|
|%p|os.date\("%p", 1487356783\)|上午AM 下午PM|AM|
|%S|os.date\("%S", 1487356783\)|秒钟[00-61]|43|
|%w|os.date\("%w", 1487356783\)|星期几 (星期日为0) [0-6]|6|
|%x|os.date\("%x", 1487356783\)|标准的日期串|02/18/17|
|%X|os.date\("%X", 1487356783\)|标准的时间串|02:39:43|
|%y|os.date\("%y", 1487356783\)|不带世纪的年份|17|
|%Y|os.date\("%Y", 1487356783\)|带世纪部分的年份|2017|
|%%|os.date\("%%", 1487356783\)|百分号|%|

更多 [os.date](https://cloudwu.github.io/lua53doc/manual.html#pdf-os.date) 使用示例，可参考 [`sys.toast` 中实时显示当前日期时间的代码](/docs/handbook/sys/sys.toast.md)

---

Source: [获取当前毫秒级时间戳 (sys.mtime)](https://xxtouch.app/docs/handbook/sys/sys.mtime.md)
Path: handbook/sys/sys.mtime.md

# 获取当前毫秒级时间戳 (sys.mtime)


## 声明

```lua
时间戳 = sys.mtime()
```


## 返回值

- 时间戳
    整数型，返回毫秒级 UNIX 时间戳


## 示例

```lua
local ms = sys.mtime()
screen.keep()
sys.alert('一次 screen.keep 耗时：'..sys.mtime()-ms..'毫秒')
```
**注**：上述代码中使用了非本章函数 [`screen.keep`](/docs/handbook/screen/screen.keep.md)

---

Source: [反注册监听一个事件 (thread.unregister_event)](https://xxtouch.app/docs/handbook/thread/thread.unregister_event.md)
Path: handbook/thread/thread.unregister_event.md

# 反注册监听一个事件 (thread.unregister_event)


## 声明

```lua
thread.unregister_event(事件名, 事件ID)
```


## 参数

- 事件名
    字符串型
- 事件 ID
    整数型


## 说明

> 反注册监听一个事件


## 示例

参考 [本章末尾的综合示例](/docs/handbook/thread/samples.md)

---

Source: [设置触摸事件对象移动步长 (:step_len)](https://xxtouch.app/docs/handbook/touch/touchm_step_len.md)
Path: handbook/touch/touchm_step_len.md

# 设置触摸事件对象移动步长 (:step_len)


## 声明

```lua
触摸事件 = 触摸事件:step_len(步长)
```


## 参数

- 步长
    整数型，可选参数，默认为 2


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 设置当前触摸事件对象使用 move 方法滑动的步长


## 示例

```lua
-- 模拟一个手指于点 100, 100 的位置接触屏幕，以步长为 3 、每步延迟为 0.2 毫秒的速度滑动到点 200, 200 的位置离开屏幕
touch.on(100, 100):step_len(3):step_delay(0.2):move(200, 200):off()
```

---

Source: [导入一个视频文件到相册 (utils.video_to_album)](https://xxtouch.app/docs/handbook/utils/utils.video_to_album.md)
Path: handbook/utils/utils.video_to_album.md

# 导入一个视频文件到相册 (utils.video_to_album)


## 声明

```lua
utils.video_to_album(视频文件名)
```


## 参数

- 视频文件名
    文本型，视频文件的文件名，支持的格式有 mp4、m4v、mov


## 说明

> 将 mp4、m4v、mov 视频保存到相册


## 示例

```lua
utils.video_to_album("/var/mobile/1.mp4")
```

---

Source: [断开当前的 VPN 连接 (vpnconf.disconnect)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.disconnect.md)
Path: handbook/vpnconf/vpnconf.disconnect.md

# 断开当前的 VPN 连接 (vpnconf.disconnect)


## 声明

```lua
操作成败 = vpnconf.disconnect()
```


## 返回值

- 操作成败
    布尔型，操作成功 (不是断开连接成功) 返回 true，操作失败返回 false，操作失败通常是因为没有选中的配置


## 示例

```lua
local success = vpnconf.disconnect()
if success then
    sys.alert('操作成功，正在断开连接……')
else
    sys.alert('当前并无选中任何 VPN 配置，成功创建 VPN 之后，记得调用 vpnconf.select 选中它')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [webview 使用示例](https://xxtouch.app/docs/handbook/webview/samples.md)
Path: handbook/webview/samples.md

# webview 使用示例

## 一个演示

```lua
local html = [=[
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<!DOCTYPE html>
<html>
    <head>
    <script src="/js/jquery.min.js"></script>
    <script src="/js/jquery.json.min.js"></script>
    <script type="text/javascript">
    $(document).ready(function(){
        $("#toast_content").val("toast内容");
        $("#close_page").click(function(){
            $.post(
                "/proc_queue_push",
                '{"key": "来自webview的消息","value": "关闭页面"}',
                function(){}
            );
        });

        $("#show_toast").click(function(){
            $.post(
                "/proc_put",
                $.toJSON({
                    key:"toast内容",
                    value:$("#toast_content").val()
                }),
                function(){}
            );
            $.post(
                "/proc_queue_push",
                '{"key": "来自webview的消息","value": "显示toast"}',
                function(){}
            );
        });

        $("#slide_down").click(function(){
            $.post(
                "/proc_queue_push",
                '{"key": "来自webview的消息","value": "往下滑动"}',
                function(){}
            );
            $(this).hide();
        });

        $("#full_vertical").click(function(){
            $.post(
                "/proc_queue_push",
                '{"key": "来自webview的消息","value": "竖屏全屏"}',
                function(){}
            );
        });

        $("#full_landscape").click(function(){
            $.post(
                "/proc_queue_push",
                '{"key": "来自webview的消息","value": "横屏全屏"}',
                function(){}
            );
        });
    });
    </script>
    </head>
    <body>
        <p>XXTouch WebView 演示</p>
        <p><button id="close_page" type="button">点我关闭页面</button></p>
        <p><button id="show_toast" type="button">显示一个toast</button><input type="text" id="toast_content" /></p>
        <p><button id="full_vertical" type="button">竖屏全屏</button><button id="full_landscape" type="button">横屏全屏</button></p>
        <p><button id="slide_down" type="button">视图往下滑动</button></p>
        <select>
            <option value="o1">第1个选项</option>
            <option value="o2">第2个选项</option>
            <option value="o3">第3个选项</option>
            <option value="o4">第4个选项</option>
        </select>
    </body>
</html>
]=]
--
local w, h = screen.size()
local factor = screen.scale_factor()
--
webview.show{ -- 重置 webview 位置到左上角
    x = 0,
    y = 0,
    width = w - 40 * factor,
    height = (500) * factor,
    alpha = 0,
    animation_duration = 0,
}
--
webview.show{ -- 从左上角用0.3秒的时间滑动出来
    html = html,
    x = 20 * factor,
    y = 50 * factor,
    width = (w - 40 * factor),
    height = (500) * factor,
    corner_radius = 10,
    alpha = 0.7,
    animation_duration = 0.3,
}
--
proc_queue_clear("来自webview的消息", "") -- 清空需要监听的字典的值
local eid = thread.register_event( -- 注册监听字典状态有值事件
    "来自webview的消息",
    function(val)
        if val == "关闭页面" then
            webview.show{
                x = 20 * factor,
                y = 500 * factor * 2,
                width = (w - 40 * factor),
                height = (500 - 70) * factor,
                corner_radius = 10,
                alpha = 0,
                animation_duration = 0.8,
            }
            sys.msleep(800)
            webview.destroy()
            sys.toast("页面线程结束")
            return true -- 返回 true 停止当前监听
        elseif val == "往下滑动" then
            webview.show{
                x = 20 * factor,
                y = (50 + 300) * factor, -- 纵坐标 + 300
                width = (w - 40  * factor),
                height = (500 - 70) * factor, -- 往下滑动按钮被隐藏了，高度调整
                corner_radius = 10,
                alpha = 0.7,
                animation_duration = 0.5, -- 耗时 0.5 秒
            }
        elseif val == "竖屏全屏" then
            webview.show{} -- 此处将会把 webview 置为全屏
        elseif val == "横屏全屏" then
            webview.show{rotate=90} -- 此处将会把 webview 置为横屏全屏
        elseif val == "显示toast" then
            sys.toast(proc_get("toast内容"))
        end
    end
)
--
sys.msleep(3000)
sys.toast("主线程结束")
```
**注**：上述代码中使用了非本章函数 [`screen.size`](/docs/handbook/screen/screen.size.md)、[`proc_queue_clear`](/docs/handbook/proc/proc_queue_clear.md)、[`thread.register_event`](/docs/handbook/thread/thread.register_event.md)、[`proc_get`](/docs/handbook/proc/proc_get.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [重新加载当前正在展示的配置界面 (xui.reload)](https://xxtouch.app/docs/handbook/xui/xui.reload.md)
Path: handbook/xui/xui.reload.md

# 重新加载当前正在展示的配置界面 (xui.reload)


## 声明

```lua
xui.reload()
```


## 说明

> 若当前没有正在展示的配置界面，则不执行任何操作
> 请控制好该函数的调用频率，过高可能导致 App 卡顿
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.reload()
```

---

Source: [关闭应用程序 (app.close)](https://xxtouch.app/docs/handbook/app/app.close.md)
Path: handbook/app/app.close.md

# 关闭应用程序 (app.close)


## 声明

```lua
app.close(应用包标识符 或 进程号)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
- 进程号
    整数型，需要关闭的应用的进程号


## 说明

> 关闭应用程序，参数可以是应用包标识符或进程号。若应用未在运行，则不执行任何操作，该调用不会失败
> 此操作为不可拒绝的强制终止，目标应用被关闭时不会收到任何通知

## 示例

参考 [`app.run`](/docs/handbook/app/app.run.md) 示例
参考 [`app.bundles`](/docs/handbook/app/app.bundles.md) 示例

---

Source: [清理 IDFA/V (clear.idfav)](https://xxtouch.app/docs/handbook/clear/clear.idfav.md)
Path: handbook/clear/clear.idfav.md

# 清理 IDFA/V (clear.idfav)


## 声明

```lua
旧IDFAV信息 = clear.idfav([ 新IDFAV信息 ])
```


## 参数

- 新 IDFAV 信息
    文本型，可选参数，表示指定使用这些信息作为设备的新的 idfav 信息，不传入参数表示清理后让系统自动生成。可传入 "read" 表示不清理仅读取设备的 IDFAV 信息

## 返回值

- 旧 IDFAV 信息
    文本型 或 nil，返回设备原来的 idfav 信息，如果操作失败，则返回 nil


## 说明

> 重置设备 IDFA 和 IDFV 等标识信息
> 若传入的 idfav 信息不正确，操作将失败并返回 nil
> 若不传入参数，将清除设备当前的 idfav 信息，iOS 系统随后会重新随机分配 idfav
> 返回的 idfav 信息文本可自行保存到文件，需要恢复时再将其作为参数传回即可


## 示例

```lua
-- 备份并清理 idfav 信息
app.quit('*') -- 关闭所有应用
local old_idfavs = clear.idfav("read") -- 读取现有的 idfav 信息
local ok, err = file.writes(XXT_SCRIPTS_PATH.."/old_idfavs.txt", old_idfavs) -- 将现有的 idfav 信息保存到文件
if ok then
    clear.idfav() -- 清理 idfav 信息
    sys.alert("备份成功")
else
    sys.alert("备份失败\n"..tostring(err))
end

-- 从文件中恢复 idfav 信息
app.quit('*') -- 关闭所有应用
local old_idfavs, err = file.reads(XXT_SCRIPTS_PATH.."/old_idfavs.txt") -- 读取保存的 idfav 信息
if old_idfavs then
    local current_idfavs = clear.idfav(old_idfavs)
    if current_idfavs then
        local ok, err = file.writes(XXT_SCRIPTS_PATH.."/current_idfavs.txt", current_idfavs) -- 将现有的 idfav 信息保存到另一个文件
        sys.alert("恢复 idfav 信息成功")
    else
        sys.alert("恢复 idfav 信息失败")
    end
else
    sys.alert("文件打开失败\n"..tostring(err))
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`file.reads`](/docs/handbook/file/file.reads.md)、[`file.writes`](/docs/handbook/file/file.writes.md)、[`app.quit`](/docs/handbook/app/app.quit.md)

---

Source: [解锁设备屏幕旋转锁 (device.unlock_orien)](https://xxtouch.app/docs/handbook/device/device.unlock_orien.md)
Path: handbook/device/device.unlock_orien.md

# 解锁设备屏幕旋转锁 (device.unlock_orien)


## 声明

```lua
device.unlock_orien()
```

## 示例

```lua
device.unlock_orien()
```

---

Source: [配置对话框的圆角半径 (:set_corner_radius)](https://xxtouch.app/docs/handbook/dialog/dialogm_set_corner_radius.md)
Path: handbook/dialog/dialogm_set_corner_radius.md

# 配置对话框的圆角半径 (:set_corner_radius)


## 声明

```lua
对话框对象 = 对话框对象:set_corner_radius(圆角半径)
```

## 参数

- 圆角半径
    整数型，圆角半径，0 为方角

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 配置对话框的圆角半径，适用于需要圆角对话框的场景
> 该方法仅在使用 webview 引擎的 dialog 上有效


## 示例

```lua
local dlg = dialog()
dlg:set_frame(0, 0, 600, 800)
dlg:set_corner_radius(50)
dlg:show()
```

---

Source: [统计一个文本文件的总行数 (file.line_count)](https://xxtouch.app/docs/handbook/file/file.line_count.md)
Path: handbook/file/file.line_count.md

# 统计一个文本文件的总行数 (file.line_count)


## 声明

```lua
行数 = file.line_count(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- 行数
    整数型 或 nil，返回文件总行数，空文件将返回 0，文件不存在返回 nil


## 说明

> 统计一个文本文件的总行数，空文件将返回 0


## 示例

```lua
local linecount = file.line_count("/var/mobile/1.txt")
if linecount then
    sys.alert("`/var/mobile/1.txt` 一共有 "..linecount.." 行")
else
    sys.alert("`/var/mobile/1.txt` 不是文件")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [复位手柄状态 (:reset)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_reset.md)
Path: handbook/gamepad/gamepadm_reset.md

# 复位手柄状态 (:reset)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:reset()
```

## 返回值

- 状态
    布尔型，复位成功返回 true，设备断开、忙或输入发送失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

> 松开全部按键，并使两个摇杆和方向键回中。

## 示例

```lua
local pad = assert(gamepad.connect())

assert(pad:set_stick("left", 1, 0))
assert(pad:reset())
assert(pad:disconnect())
```

---

Source: [发起 PUT 请求 (http.put)](https://xxtouch.app/docs/handbook/http/http.put.md)
Path: handbook/http/http.put.md

# 发起 PUT 请求 (http.put)


## 声明

```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.put(URL [, 超时秒, 请求头, 请求主体数据, URL不ESCAPE ])
```

## 声明（命名参数）

**20250625 支持，20260402 以后版本支持进度参数**
```lua
HTTP状态码, 返回头JSON文本, 返回主体 = http.put{
    url = URL;
    timeout = 超时秒;
    headers = 请求头;
    params = Query参数;

    -- 以下请求主体参数不可并存，优先顺序为 multipart > data > json > upload_file
    multipart = 请求主体multipart表单;
    data = 请求主体数据;
    json = 请求主体JSON;
    upload_file = 请求主体上传文件路径;

    download_file = 请求成功返回主体保存文件路径;
    progress = 进度回调函数;
    progress_interval_ms = 进度回调间隔毫秒;
}
```


## 参数

- URL
    文本型，需要请求的 URL 地址，该方法默认会对 URL 进行 escape 处理，如不需要可参考 **URL 不 ESCAPE** 参数说明
- 超时秒
    实数型，可选参数，请求超时时间，单位秒，默认 10
- 请求头
    表型，可选参数，发出的请求的头部信息，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- Query 参数
    表型，可选参数，发出的请求的 Query 参数，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体数据
    字符串型，可选参数，使用 PUT 发送出去的内容，默认为空字符串
    **20250625** 如果为表型，则以 application/x-www-form-urlencoded 的方式编码发送
- 请求主体 multipart 表单
    表型，可选参数，使用 PUT 发送出去的 multipart 表单数据，形式 \{field1 = value1, field2 = value2, ...\}，默认 \{\}
- 请求主体 JSON
    表型，可选参数，以 application/json 的方式编码发送
- 请求主体上传文件路径
    文本型，可选参数，将文件数据直接作为请求体发送
- 请求成功返回主体保存文件路径
    文本型，可选参数，如果有该参数，则请求成功后返回主体为保存的文件路径
- 进度回调函数
    函数型，可选参数，**20260402 以后版本支持**。请求上传或下载进度变化时调用，回调函数第一个参数为当前进度信息
- 进度回调间隔毫秒
    整数型，可选参数，**20260402 以后版本支持**。控制进度回调触发间隔，单位毫秒
- **URL 不 ESCAPE**
    布尔型，可选参数，true 表示不对 URL 进行 escape 直接请求，默认 false
    对 URL 进行自定义 escape 可参考 [lcurl 模块](/docs/handbook/open-source/lcurl.md) 的 [easy:escape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:escape)、[easy:unescape](https://lua-curl.github.io/lcurl/modules/lcurl.html#easy:unescape)


## 返回值

- HTTP 状态码
    整数型，返回当次请求的 http 状态码，请求超时返回 -1
- 返回头 JSON 文本
    文本型 或 nil，请求完成返回的 JSON 形式头部信息，请求超时返回 nil
- 返回主体
    字符串型 或 nil，请求完成返回的内容，如果请求主体保存到文件，则此值为文件路径，请求超时返回 nil


## 说明

> 使用 HTTP/1.1 协议的 PUT 方法发送数据到网络中，它与 POST 用法一致
> **该函数可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**

进度回调函数接收的 `info` 结构如下：

```lua
{
    count_of_bytes_sent = 已发送字节数;
    count_of_bytes_expected_to_send = 预计需要发送字节数;
    count_of_bytes_received = 已接收字节数;
    count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
```


## 示例

```lua
local code, res_headers, body = http.put("https://httpbin.org/put?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)", -- 模拟 IE8 的请求
    ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
}, "需要发送过去的数据")
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 示例（命名参数）

```lua
local code, res_headers, body = http.put{
    url = "https://httpbin.org/put";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
        ["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
    data = "需要发送过去的数据";
}
if code == 200 then -- 如果返回的状态码是 HTTP_OK
    sys.alert(body)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从图片对象创建拷贝图片对象 (:copy)](https://xxtouch.app/docs/handbook/image/imagem_copy.md)
Path: handbook/image/imagem_copy.md

# 从图片对象创建拷贝图片对象 (:copy)


## 声明

```lua
图片拷贝份 = 图片:copy()
```


## 返回值

- 图片拷贝份
    图片对象，返回原始图片对象的拷贝


## 说明

> 从图片对象创建拷贝图片对象
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用


## 示例

```lua
scrn = screen.image()
img2 = scrn:copy()
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)

---

Source: [! 连接全局硬件键盘 (key.connect_global_keyboard)](https://xxtouch.app/docs/handbook/key/key.connect_global_keyboard.md)
Path: handbook/key/key.connect_global_keyboard.md

# ! 连接全局硬件键盘 (key.connect_global_keyboard)

> **该函数在 20260805 以后版本方可使用**

## 声明

```lua
硬件键盘对象, 错误信息 = key.connect_global_keyboard([配置属性])
```

## 参数

- 配置属性
    表型，可选参数，与 [`key.connect_keyboard`](key.connect_keyboard.md) 使用相同的默认属性和约束。

## 返回值

- 硬件键盘对象
    硬件键盘对象，连接成功时返回；连接失败时返回 `nil`。
- 错误信息
    文本型，连接失败时返回错误信息。

连接失败时，两个返回值合起来为 `nil, error`。

## 说明

> 创建并连接全局硬件键盘。连接等待期间会隐式让出，在函数返回之前，其他[线程](/docs/handbook/thread/index.md)可能获得执行机会。

- 连接后，原有 `key.press`、`key.down`、`key.up`、`key.send_text` 以及 `key(...):press/down/up` 的普通键盘和数字小键盘按键会通过该对象输入
- 媒体键和厂商自定义键仍保持原有行为
- 没有全局硬件键盘时，原有接口行为不变。
- `key.down` 与对应的 `key.up` 会保持配对，即使两次调用之间连接状态发生变化，也不会造成重复输入或错误释放
- 同一时间只能连接一个全局硬件键盘。未完成连接时再次调用，或已有全局硬件键盘时再次连接，都会返回失败。

## 示例

```lua
local keyboard, err = key.connect_global_keyboard({
    Product = "XXTouch Keyboard",
})
assert(keyboard, err)

key.press("A")
key.send_text("Hello")

local current = key.get_global_keyboard()
assert(current == keyboard)

assert(key.disconnect_global_keyboard())
```

---

Source: [获取硬件鼠标连接状态 (:is_connected)](https://xxtouch.app/docs/handbook/mouse/mousem_is_connected.md)
Path: handbook/mouse/mousem_is_connected.md

# 获取硬件鼠标连接状态 (:is_connected)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
是否连接 = 鼠标对象:is_connected()
```


## 返回值

- 是否连接
    布尔型，硬件鼠标仍处于连接状态时返回 `true`，否则返回 `false`


## 说明

> 获取当前硬件鼠标对象的连接状态。


## 示例

```lua
local m = assert(mouse.connect())
assert(m:is_connected())
assert(m:disconnect())
assert(not m:is_connected())
```

---

Source: [lcurl 模块](https://xxtouch.app/docs/handbook/open-source/lcurl.md)
Path: handbook/open-source/lcurl.md

# lcurl 模块

[lcurl 手册地址](https://lua-curl.github.io/lcurl/modules/lcurl.html)

---

## URL 百分号编解码（escape / unescape）

> 关键词：URL 编码、URI 编码、百分号编码、URLEncode、URLDecode、URLEscape、PercentEscape

```lua
local curl = require('lcurl')
local e = curl.easy()
--
print(e:escape('abcd$%^&*()'))                 -- 输出 "abcd%24%25%5E%26%2A%28%29"
--
print(e:unescape('abcd%24%25%5E%26%2A%28%29')) -- 输出 "abcd$%^&*()"
--
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

## 基于 lcurl 实现的 httpGet 示例

```lua
function httpGet(url) -- 也能请求 ftp 资源 (该函数已内置，此处仅用于演示 lcurl 的用法)
    if (url:sub(1, 6) ~= "ftp://" and
        url:sub(1, 8) ~= "https://" and
        url:sub(1, 7) ~= "http://") then
        url = "https://"..url
    end
    local curl = require("curl.safe")
    local buffer_t = {}
    local write_f = function(s)
        buffer_t[#buffer_t + 1] = s
    end
    local noerr, err = pcall(function()
        curl.easy()
            :setopt(curl.OPT_URL, url)
            :setopt(curl.OPT_CONNECTTIMEOUT, 60)
            :setopt_writefunction(write_f)
        :perform()
    end)
    if (noerr) then
        return table.concat(buffer_t)
    else
        return nil, err
    end
end
```
**注**：上述代码中使用了非本章函数 [table.concat](https://cloudwu.github.io/lua53doc/manual.html#pdf-table.concat)

---

Source: [获取进程队列词典的尺寸 (proc_queue_size)](https://xxtouch.app/docs/handbook/proc/proc_queue_size.md)
Path: handbook/proc/proc_queue_size.md

# 获取进程队列词典的尺寸 (proc_queue_size)


## 声明

```lua
尺寸 = proc_queue_size(键)
```


## 参数

- 键
    字符串型

## 返回值

- 尺寸
    整数型，返回该进程队列词典中的有效条目数


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> 获取进程队列词典的尺寸


## 示例

```lua
local size = proc_queue_size("billnos")
if size ~= 0 then
    print("has "..size.." bill(s)")
else
    print("no bill")
end
```

---

Source: [屏幕多点颜色匹配 (screen.is_colors)](https://xxtouch.app/docs/handbook/screen/screen.is_colors.md)
Path: handbook/screen/screen.is_colors.md

# 屏幕多点颜色匹配 (screen.is_colors)


## 声明

```lua
是否匹配 = screen.is_colors({
    [max_miss = 允许最大未命中数,]
    [xy_tolerance = 坐标容差,]
    [csim_algorithm = 颜色相似度算法,]
    {横坐标*, 纵坐标*, 颜色*},
    {横坐标*, 纵坐标*, 颜色*},
    ...
}[, 颜色相似度])
```


## 参数

- 允许最大未命中数
    整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算匹配
- 坐标容差（自 20250228 版本起支持）
    整数型，可选参数，允许的坐标偏移量，超出该值的点将被视为未命中，默认为 0（坐标必须完全匹配）
- 颜色相似度算法（自 20250302 版本起支持）
    整数型，可选参数，指定颜色相似度算法，默认 0
    <details>

    <summary>颜色相似度算法</summary>

    ```lua
    0 为 XXT 默认算法，梯度陡峭，差值使相似度下降很快
    1 为曼哈顿算法，梯度平滑
    2 为欧几里得算法，梯度平滑
    ```
    </details>
- 横坐标\*, 纵坐标\*
    整数型，代表其中某点坐标
- 颜色\*
    整数型，代表其中某点需要匹配的颜色值
- 颜色相似度
    整数型，可选参数，代表需要的颜色的相似度，取值范围 1~100，默认 100

## 返回值

- 是否匹配
    布尔型，所有点的颜色都匹配则返回 true，否则返回 false


## 说明

> 匹配屏幕上若干点的颜色
> 当前函数坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响


## 示例

```lua
if screen.is_colors({
    { 509, 488, 0xec1c23}, -- 如果坐标 (509, 488) 的颜色与 0xec1c23 相似度在 90% 以上
    { 514, 470, 0x00adee}, -- 同时坐标 (514, 470) 的颜色与 0x00adee 相似度在 90% 以上
    { 508, 478, 0xffc823}, -- 同时坐标 (508, 478) 的颜色与 0xffc823 相似度在 90% 以上
    { 511, 454, 0xa78217}, -- 同时坐标 (511, 454) 的颜色与 0xa78217 相似度在 90% 以上
    { 521, 433, 0xd0d2d2}, -- 同时坐标 (521, 433) 的颜色与 0xd0d2d2 相似度在 90% 以上
}, 90) then                -- 则匹配
    sys.alert("匹配！")
else
    sys.alert("不匹配！")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [命令执行相关示例代码 (os.execute)](https://xxtouch.app/docs/handbook/supplement/os.execute.md)
Path: handbook/supplement/os.execute.md

# 命令执行相关示例代码 (os.execute)

`os.execute` 依赖于 Shell，iOS 越狱环境的 Shell 可能是 `Bash` 或 `Zsh`。
巨魔版 XXTouch 不支持 `os.execute`。
建议尽量避免使用 `os.execute`。

## 重启设备

```lua
-- os.execute('reboot')
-- 建议使用如下调用替代
sys.reboot()
```

## 注销设备

```lua
-- os.execute('killall -9 SpringBoard;killall -9 backboardd')
-- 建议使用如下调用替代
sys.killall(9, 'SpringBoard', 'backboardd')
```

## 重建图标缓存

```lua
-- os.execute('su mobile -c uicache')
-- 建议使用如下调用替代
clear.caches()
```

## 创建脚本日志符号链接到脚本目录

```lua
-- os.execute('ln -s /private/var/mobile/Media/1ferver/log/sys.log /private/var/mobile/Media/1ferver/lua/scripts/脚本日志.txt')
-- 建议使用如下调用替代
lfs.link('/private/var/mobile/Media/1ferver/log/sys.log', '/private/var/mobile/Media/1ferver/lua/scripts/脚本日志.txt', true)
```


## 常用操作封装

```lua
--[[
    以下封装已经不建议使用，建议使用 XXTouch 内置的 file 模块函数替代
--]]

local function sh_escape(path) -- XXTouch 原创函数，未经 XXTouch 许可，可以用于商业用途
    path = string.gsub(path, "([ \\()<>'\"`#&*;?~$|])", "\\%1")
    return path
end

function fdelete(path) -- 删除一个文件或目录 (递归删除子项)
    assert(type(path)=="string" and path~="", 'fremove 参数异常')
    -- os.execute('rm -rf '..sh_escape(path))
    -- 建议使用如下调用替代
    file.remove(path)
end

function frename(from, to) -- 重命名 (移动) 一个文件或目录
    assert(type(from)=="string" and from~="", 'frename 参数 1 异常')
    assert(type(to)=="string" and to~="", 'frename 参数 2 异常')
    -- os.execute('mv -f '..sh_escape(from).." "..sh_escape(to))
    -- 建议使用如下调用替代
    file.move(from, to, 'mo')
end

function fcopy(from, to) -- 拷贝一个文件或目录 (递归拷贝子项)
    assert(type(from)=="string" and from~="", 'fcopy 参数 1 异常')
    assert(type(to)=="string" and to~="", 'fcopy 参数 2 异常')
    -- os.execute('cp -rf '..sh_escape(from).." "..sh_escape(to))
    -- 建议使用如下调用替代
    file.copy(from, to, 'mo')
end

function mkdir(path) -- 新建一个目录 (递归创建子目录)
    assert(type(path)=="string" and path~="", 'mkdir 参数异常')
    -- os.execute('mkdir -p '..sh_escape(path))
    -- 建议使用如下调用替代
    file.mkdir_p(path)
end

-- 以上是封装好的函数，将其复制到脚本开头即可使用。
-- 以下为调用示例（无需复制）

-- 删除 /var/mobile/1.png
fdelete("/var/mobile/1.png")

-- 将 /var/mobile/2.png 重命名为 /var/mobile/1.png
frename("/var/mobile/2.png", "/var/mobile/1.png")

-- 将 /var/mobile/1.png 移动到 /var/mobile/Media/1ferver/res/3.png
frename("/var/mobile/1.png", "/var/mobile/Media/1ferver/res/3.png")

-- 将 /var/mobile/1.png 拷贝到 /var/mobile/Media/1ferver/res/4.png
fcopy("/var/mobile/1.png", "/var/mobile/Media/1ferver/res/4.png")

-- 建立 /var/mobile/1/2/3/4/ 目录
mkdir("/var/mobile/1/2/3/4")

```

---

Source: [! 获取网络时间 (sys.net_time)](https://xxtouch.app/docs/handbook/sys/sys.net_time.md)
Path: handbook/sys/sys.net_time.md

# ! 获取网络时间 (sys.net_time)


## 声明

```lua
秒级时间戳 = sys.net_time([ 超时时间 ])
```


## 参数

- 超时时间
    实数型，可选参数，用于设置获取网络时间联网的最大等待时间 (单位：秒) ，默认 2

## 返回值

- 秒级时间戳
    整数型， 成功则返回当前网络时间的秒级 UNIX 时间戳，连接超时或未能成功获取网络时间返回 0


## 说明

> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 示例

```lua
local nt = sys.net_time() -- 获取网络时间，默认 2 秒超时，超时返回 0
--
local nt = sys.net_time(5) -- 获取网络时间，5 秒超时，超时返回 0
if nt==0 then
    sys.alert('获取网络时间失败')
else
    sys.alert(os.date('当前网络时间\n%Y-%m-%d %H:%M:%S', nt))
end
```
**注**：上述代码中使用了 [os.date 日期格式化相关](/docs/handbook/supplement/os.date.md)

---

Source: [thread 示例代码](https://xxtouch.app/docs/handbook/thread/samples.md)
Path: handbook/thread/samples.md

# thread 示例代码


```lua
tmid = thread.dispatch( -- 派发一个异步任务
    function()
        sys.msleep(2700)
        sys.toast("这是第 2.7 秒")
    end
)
--
tid = thread.dispatch( -- 派发一个异步任务
    function()
        sys.msleep(300)
        for i=1,10 do
            sys.toast("线程 2: "..i)
            sys.msleep(1000)
        end
        sys.toast("应该运行不到这里")
    end
)
--
-- iPhone 5C 双指合拢缩小相册图片示例
--
thread.dispatch(function() -- 派发一个滑动任务
    touch.on(59,165)
        :move(297,522)
        :msleep(500)
    :off()
end)
--
thread.dispatch(function() -- 再派发一个滑动任务
    touch.on(580,1049)
        :move(371,1049)
        :msleep(500)
    :off()
end)
--
proc_queue_clear("来自远方的消息")
eid = thread.register_event( -- 注册监听字典状态有值事件
    "来自远方的消息",
    function(val)
        sys.toast("收到消息："..val)
    end
)
--
sys.msleep(300)
thread.wait(tmid)
--
for i=1,10 do
    sys.toast("线程 1: "..i)
    sys.msleep(400)
end
--
thread.kill(tid) -- 杀死 线程 2
thread.unregister_event("来自远方的消息", eid) -- 取消一个字典状态有值事件
--
sys.toast("全部任务已完成")
```
**注**：上述代码中使用了非本章函数及方法  [`proc_queue_clear`](/docs/handbook/proc/proc_queue_clear.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`touch.on`](/docs/handbook/touch/touch.on.md)、[`:move`](/docs/handbook/touch/touchm_move.md)、[`:msleep`](/docs/handbook/touch/touchm_msleep.md)、[`:off`](/docs/handbook/touch/touchm_off.md)

---

Source: [设置触摸事件对象移动每步延迟 (:step_delay)](https://xxtouch.app/docs/handbook/touch/touchm_step_delay.md)
Path: handbook/touch/touchm_step_delay.md

# 设置触摸事件对象移动每步延迟 (:step_delay)


## 声明

```lua
触摸事件 = 触摸事件:step_delay(每步延迟)
```


## 参数

- 每步延迟
    实数型，可选参数，每步延迟时间，单位毫秒，默认 0.1


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 设置当前触摸事件对象使用 move 方法滑动的每步延迟


## 示例

```lua
-- 模拟一个手指于点 100, 100 的位置接触屏幕，以步长为 3 、每步延迟为 0.2 毫秒的速度滑动到点 200, 200 的位置离开屏幕
touch.on(100, 100):step_len(3):step_delay(0.2):move(200, 200):off()
```

---

Source: [生成一个 UUID (utils.gen_uuid)](https://xxtouch.app/docs/handbook/utils/utils.gen_uuid.md)
Path: handbook/utils/utils.gen_uuid.md

# 生成一个 UUID (utils.gen_uuid)


## 声明

```lua
uuid = utils.gen_uuid()
```


## 返回值

- uuid
    文本型，生成的 UUID


## 说明

> **软件版本在 1.3.8 或以上方可使用**


## 示例

```lua
nLog(utils.gen_uuid())
```

---

Source: [获取当前选择的 VPN 的状态 (vpnconf.status)](https://xxtouch.app/docs/handbook/vpnconf/vpnconf.status.md)
Path: handbook/vpnconf/vpnconf.status.md

# 获取当前选择的 VPN 的状态 (vpnconf.status)


## 声明

```lua
状态 = vpnconf.status()
```


## 返回值

- 状态
    表型 或 nil，操作成功返回状态描述表，没有选择任何 VPN 返回 nil
    <details>

    <summary>返回的状态表结构如下</summary>

    ```Lua
    {
        text = 当前状态的文字描述,
        connected = 是否已经连接成功,
    }
    ```
    </details>


## 示例

```lua
local status = vpnconf.status()
if status then
    sys.alert(table.deep_dump(status))
else
    sys.alert('当前并无选中任何 VPN 配置，成功创建 VPN 之后，记得调用 vpnconf.select 选中它')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`table.deep_dump`](/docs/handbook/ext-table/table.deep_dump.md)

---

Source: [获取配置界面的配置值 (xui.get)](https://xxtouch.app/docs/handbook/xui/xui.get.md)
Path: handbook/xui/xui.get.md

# 获取配置界面的配置值 (xui.get)


## 声明

```lua
值 = xui.get(配置分区, 配置键)
```


## 参数

- 配置分区
    文本型，配置界面中的配置分区（defaults）标识符
- 配置键
    文本型，配置界面中的控件的配置键（key）标识符


## 返回值

- 值
    任意类型，不同的控件类型会返回不同的值，如果没有该配置值，返回 nil


## 说明

> 该函数不会过滤值类型；如需保证获取的值类型合法，可先使用 `xui.setup` 校验修正再读取
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.setup('interface.xui')
local enabled = xui.get('com.yourcompany.A-Script-Bundle', 'enabled')
```

---

Source: [模拟上滑退出应用程序 (app.quit)](https://xxtouch.app/docs/handbook/app/app.quit.md)
Path: handbook/app/app.quit.md

# 模拟上滑退出应用程序 (app.quit)


## 声明

```lua
app.quit(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
    传入 `"*"` 表示退出所有


## 说明

> 该操作同样为强制终止，但与 [app.close](/docs/handbook/app/app.close.md) 不同的是，应用在退出前会收到通知，并有至多 10 秒时间保存存档，同时会清除多任务切换界面的标签
> **请不要在锁屏状态使用。该函数可能无法正常退出以 root 权限运行的 App，使用该函数退出 root 权限程序可能会导致屏幕卡住、点击图标无响应等现象。root 权限的 App 推荐使用 [app.close](/docs/handbook/app/app.close.md) 强制终止**


## 示例

```lua
-- 退出所有的 App
app.quit("*")
--
-- 退出QQ，如果QQ正在运行的话
app.quit("com.tencent.mqq")
```

---

Source: [获取屏幕旋转锁锁定状态 (device.is_orien_locked)](https://xxtouch.app/docs/handbook/device/device.is_orien_locked.md)
Path: handbook/device/device.is_orien_locked.md

# 获取屏幕旋转锁锁定状态 (device.is_orien_locked)


## 声明

```lua
是否锁定 = device.is_orien_locked()
```


## 返回值

- 是否锁定
    布尔型，返回是否已经锁定屏幕旋转锁


## 示例

```lua
if device.is_orien_locked() then
    -- 屏幕旋转已锁定
else
    -- 屏幕旋转没锁定
end
```

---

Source: [给对话框加上一个文本标签 (:add_label)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_label.md)
Path: handbook/dialog/dialogm_add_label.md

# 给对话框加上一个文本标签 (:add_label)


## 声明

```lua
对话框对象 = 对话框对象:add_label(标签内容)
```

## 参数

- 标签内容
    文本型，标签显示的文本

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 给对话框加上一个文本标签


## 示例

```lua
dialog():add_label('一个文本标签'):show()
```


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [获取一个文本文件指定行的数据 (file.get_line)](https://xxtouch.app/docs/handbook/file/file.get_line.md)
Path: handbook/file/file.get_line.md

# 获取一个文本文件指定行的数据 (file.get_line)


## 声明

```lua
行内容, 错误信息 = file.get_line(文件路径, 行号)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行号
    整数型，指定行号，0 为最后一行 \+1，负数则为倒数行号

## 返回值

- 行内容
    字符串型 或 nil，行数不够返回空字符串，文件不存在返回 nil
- 错误信息
    文本型，读取失败时的错误信息


## 说明

> 获取一个文本文件指定行的数据
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local data, err = file.get_line("/var/mobile/1.txt", 1)
if data then
    sys.alert("`/var/mobile/1.txt` 第一行的内容是 "..data)
else
    sys.alert("读取失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [判断手柄是否已连接 (:is_connected)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_is_connected.md)
Path: handbook/gamepad/gamepadm_is_connected.md

# 判断手柄是否已连接 (:is_connected)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否已连接 = 手柄对象:is_connected()
```

## 返回值

- 是否已连接
    布尔型，手柄设备仍处于连接状态返回 true，否则返回 false

## 说明

> 查询该手柄对象当前是否仍处于连接状态。

## 示例

```lua
local pad = assert(gamepad.connect())
assert(pad:is_connected())
assert(pad:disconnect())
```

---

Source: [编码 HTTP URLENCODED 表单 (http.table_to_form_urlencoded)](https://xxtouch.app/docs/handbook/http/http.table_to_form_urlencoded.md)
Path: handbook/http/http.table_to_form_urlencoded.md

# 编码 HTTP URLENCODED 表单 (http.table_to_form_urlencoded)

## 声明

```lua
编码好的表单文本 = http.table_to_form_urlencoded(需要编码的表)
```

## 参数

- 需要编码的表
    表型

## 返回值

- 编码好的表单文本
    文本型

## 说明

> **该函数在 20250313 以后版本方可使用**

## 示例

```lua
form = http.table_to_form_urlencoded{
    num = 1,
    str = '你好',
    arr = {12, 34, '好'},
}

nLog(form) -- arr%5B0%5D=12&arr%5B1%5D=34&arr%5B2%5D=%E5%A5%BD&str=%E4%BD%A0%E5%A5%BD&num=1

c, h, r = http.get('https://httpbin.org/get?'..form, 10, {}, true) -- 通过 GET Query 提交表单，URL 默认会自动 Escape，除非最后一个参数是 true
nLog(r)

c, h, r = http.post('https://httpbin.org/post', 10, {}, form) -- 通过 POST 提交表单
nLog(r)
```

---

Source: [从图片对象截取部分新建拷贝图片对象 (:crop)](https://xxtouch.app/docs/handbook/image/imagem_crop.md)
Path: handbook/image/imagem_crop.md

# 从图片对象截取部分新建拷贝图片对象 (:crop)


## 声明

```lua
截取的图片 = 图片:crop([左, 上, 右, 下])
```


## 参数

- 左, 上, 右, 下
    整数型，可选参数，原始图像中的区域左上右下坐标，默认 0, 0, 原图宽-1, 原图高-1

## 返回值

- 截取的图片
    图片对象，返回从原始图片对象截取的图片对象


## 说明

> 从图片对象截取部分新建拷贝图片对象
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用


## 示例

```lua
scrn = screen.image()
img2 = scrn:crop(100, 100, 200, 200)
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)

---

Source: [获取当前全局硬件键盘 (key.get_global_keyboard)](https://xxtouch.app/docs/handbook/key/key.get_global_keyboard.md)
Path: handbook/key/key.get_global_keyboard.md

# 获取当前全局硬件键盘 (key.get_global_keyboard)

> **该函数在 20260805 以后版本方可使用**

## 声明

```lua
硬件键盘对象 = key.get_global_keyboard()
```

## 返回值

- 硬件键盘对象
    当前已连接的全局硬件键盘对象；没有可用对象时返回 `nil`。

## 说明

> 调用 `key.get_global_keyboard()` 获取由 [`key.connect_global_keyboard`](key.connect_global_keyboard.md) 连接的全局硬件键盘对象。

在未连接、正在连接或设备已经断开时，本函数均返回 `nil`。

## 示例

```lua
local keyboard = key.get_global_keyboard()
if keyboard then
    assert(keyboard:press("RETURN"))
end
```

---

Source: [获取硬件鼠标创建属性 (:get_properties)](https://xxtouch.app/docs/handbook/mouse/mousem_get_properties.md)
Path: handbook/mouse/mousem_get_properties.md

# 获取硬件鼠标创建属性 (:get_properties)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
属性 = 鼠标对象:get_properties()
```


## 返回值

- 属性
    表型，创建设备时保存的配置属性副本


## 说明

> 返回创建时保存的属性副本，其中可能包含由系统管理的属性。它不是实时系统状态，iOS 实际采用的值可能不同。


## 示例

```lua
local m = assert(mouse.connect())
local properties = m:get_properties()
print(properties.Product)
print(properties.Transport)
assert(m:disconnect())
```

---

Source: [lunix 模块](https://xxtouch.app/docs/handbook/open-source/lunix.md)
Path: handbook/open-source/lunix.md

# lunix 模块

[lunix 手册](/pdf/lunix.pdf)

---

## 更改文件权限

```lua
local unix = require("unix")
unix.chown("/var/mobile/Media/1ferver/1ferver.conf", 501, 501)
unix.chmod("/var/mobile/Media/1ferver/1ferver.conf", 6 * 8^2 + 4 * 8^1 + 4 * 8^0)
```

---

Source: [向进程队列词典头部压入一个值 (proc_queue_push_front)](https://xxtouch.app/docs/handbook/proc/proc_queue_push_front.md)
Path: handbook/proc/proc_queue_push_front.md

# 向进程队列词典头部压入一个值 (proc_queue_push_front)


## 声明

```lua
尺寸 = proc_queue_push_front(键, 值)
```

## 参数

- 键
    字符串型，代表键
- 值
    字符串型，代表需要压入的值

## 返回值

- 尺寸
    整数型，压入值之后，返回该队列的尺寸，如果返回 0 ，则为压入失败


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> **进程队列词典的队列尺寸不能大于 10000，尺寸超过的队列将丢弃最先压入的值**
> 往进程队列词典头部压入一个值，压入值之后，返回该队列的尺寸
> 不能压入空字符串


## 示例

```lua
local size = proc_queue_push_front("billnos", "name")
if size ~= 0 then
    print("has "..size.." bill(s)")
else
    print("failed")
end
```

---

Source: [多点相似度模式找色 (screen.find_color)](https://xxtouch.app/docs/handbook/screen/screen.find_color-cs.md)
Path: handbook/screen/screen.find_color-cs.md

# 多点相似度模式找色 (screen.find_color)


## 声明

```lua
横坐标, 纵坐标 = screen.find_color({
    [find_all = 是否搜索多个结果,]
    [max_results = 最大结果数,]
    [max_miss = 允许最多未命中数,]
    [csim_algorithm = 颜色相似度算法,]
    {起始点横坐标, 起始点纵坐标, 起始点颜色[, 起始点相似度]},
    {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
    {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
    ...
} [, 全局相似度, 左, 上, 右, 下 ])
```


## 参数

- 是否搜索多个结果
    布尔型，可选参数，这个标签设置为 true 会返回范围内所有匹配位置的一个表，格式为 \{\{x1, y1\}, \{x2, y2\}, ...\}，默认 false
- 最大结果数
    整数型，可选参数，当 find_all (是否搜索多个结果)  标签设置为 true 的时候，这个表示最多返回结果数，最多可以设为 1000，默认 100
- 允许最多未命中数
    整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算找到
- 颜色相似度算法 20250302
    整数型，可选参数，颜色相似度算法，默认 0
    <details>

    <summary>颜色相似度算法</summary>

    ```lua
    0 为 XXT 默认算法，梯度陡峭，差值使相似度下降很快
    1 为曼哈顿算法，梯度平滑
    2 为欧几里得算法，梯度平滑
    ```
    </details>
- 起始点横坐标, 起始点纵坐标
    整数型，代表起始坐标，它并不是限制找色的范围为固定这一点，而仅仅是给偏移位置一个相对坐标。若不需要使用偏移，可填 0, 0
- 起始点颜色
    整数型，代表需要搜索的那一点的颜色
- 起始点相似度
    整数型，可选参数，需要搜索的那一点颜色的相似度，取值范围 1~100，默认 100
- 偏移点横坐标\*, 偏移点纵坐标\*
    整数型，代表一个偏移位置坐标
- 偏移点颜色\*
    整数型，代表偏移位置需要匹配的颜色
- 偏移点相似度\*
    整数型，可选参数，偏移位置的颜色的相似度，取值范围 -100~100，默认 100，负相似度意味着匹配小于该绝对值的相似度
- 全局相似度
    整数型，可选参数，如果没有给单个点设置相似度，那么每一点都会用这个相似度，取值范围 1~100，默认 100
- 左, 上, 右, 下
    整数型，可选参数，代表搜索区域，默认 全屏


## 返回值

- 横坐标, 纵坐标
    整数型，返回匹配色的第一个色的坐标，搜索失败返回 -1, -1


## 说明

> 使用相似度模式查找，获取区域中第一个完全匹配的多点颜色结构的位置
> 当前函数坐标值参数及返回值均受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响


## 示例

```lua
x, y = screen.find_color({
    {  0,   0, 0xec1c23},
    { 12,  -3, 0xffffff, 85},
    {  5, -18, 0x00adee},
    { -1, -10, 0xffc823},
    {  2, -34, 0xa78217},
    { 12, -55, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
--[[
    在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90
    且它的相对坐标 (12, -3) 的位置的颜色与 0xffffff 相似度大于 85
    且它的相对坐标 (5, -18) 的位置的颜色与 0x00adee 相似度大于 90
    且…… (后面的同理) 都能匹配的那个点
--]]
--
-- 等效代码如下：
--
x, y = screen.find_color({
    { 509, 488, 0xec1c23},
    { 521, 485, 0xffffff, 85},
    { 514, 470, 0x00adee},
    { 508, 478, 0xffc823},
    { 511, 454, 0xa78217},
    { 521, 433, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
--[[
    在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90
    且它的相对坐标 (521-509, 485-488) 的位置的颜色与 0xffffff 相似度大于 85
    且它的相对坐标 (514-509, 470-488) 的位置的颜色与 0x00adee 相似度大于 90
    且…… (后面的同理) 都能匹配的那个点
--]]
--
-- 不换行无缩进就是这个效果：
x, y = screen.find_color({ {0,0,0xec1c23},{12,-3,0xffffff,85},{5,-18,0x00adee},{-1,-10,0xffc823},{2,-34,0xa78217},{12,-55,0xd0d2d2},},90,0,0,100,100)
--
x, y = screen.find_color({ -- 反匹配演示，在 5C 主屏幕运行可获得结果
    { 516,  288, 0xffffff },
    { 519,  286, 0xffffff },
    { 521,  289, 0xffffff },
    { 516,  296, 0xffffff },
    { 522,  297, 0xffffff },
    { 520,  295, 0xffffff, -10 }, -- 这一点颜色与 0xffffff 相似度小于 10 才匹配，下同
    { 515,  291, 0xffffff, -10 },
    { 518,  284, 0xffffff, -10 },
    { 523,  298, 0xffffff, -10 },
    { 514,  298, 0xffffff, -10 },
    { 514,  296, 0xffffff, -10 },
}, 90) -- 不写区域参数表示全屏找
--
results = screen.find_color({ -- 范围匹配全输出演示
    {  527,  278, 0xde1d26 },
    {  524,  285, 0x007aff },
    {  555,  292, 0xe4ddc9 },
    {  536,  314, 0xffde02 },
    {  502,  291, 0xffde02 },
    {  502,  283, 0xe4ddc9 },
    find_all = true, -- 带这个标签将返回范围所有匹配的位置的一个表，格式为 { {x1, y1}, {x2, y2}, ...}
}, 90) -- 不写区域参数表示全屏找
```

---

Source: [string 库的相关应用](https://xxtouch.app/docs/handbook/supplement/string-samples.md)
Path: handbook/supplement/string-samples.md

# string 库的相关应用


## 基本函数

|函数|描述|示例|结果|
|----|----|----|----|
|len|计算字符串长度|string.len\("abcd"\)|4|
|rep|返回字符串s的n个拷贝|string.rep\("abcd",2\)|abcdabcd|
|lower|返回字符串全部字母小写|string.lower\("AbcD"\)|abcd|
|upper|返回字符串全部字母大写|string.upper\("AbcD"\)|ABCD|
|format|格式化字符串|string.format\("the value is:%d",4\)|the value is:4|
|sub|从字符串里截取字符串|string.sub\("abcd",2\)|bcd|
|||string.sub\("abcd",-2\)|cd|
|||string.sub\("abcd",2,-2\)|bc|
|||string.sub\("abcd",2,3\)|bc|
|find|在字符串中查找(显示位置)|string.find\("cdcdcdcd","ab"\)|nil|
|||string.find\("cdcdcdcd","cd"\)|1 2|
|||string.find\("cdcdcdcd","cd",7\)|7 8|
|match|在字符串中查找(显示内容)|string.match\("cdcdcdcd","ab"\)|nil|
|||string.match\("cdcdcdcd","cd"\)|cd|
|gsub|在字符串中替换|string.gsub\("abcdabcd","a","z"\)|zbcdzbcd 2|
|||string.gsub\("aaaa","a","z",3\)|zzza 3|
|byte|返回字符的整数形式|string.byte\("ABCD",4\)|68|
|char|将整型数字转成字符并连接|string.char\(97,98,99,100\)|abcd|


## 基本模式串

|字符类|描述|示例|结果|
|------|----|----|----|
|.|任意字符|string.find\("","."\)|nil|
|%s|空白符|string.find\("ab cd","%s%s"\)|3 4|
|%S|非空白符|string.find\("ab cd","%S%S"\)|1 2|
|%p|标点字符|string.find\("ab,.cd","%p%p"\)|3 4|
|%P|非标点字符|string.find\("ab,.cd","%P%P"\)|1 2|
|%c|控制字符|string.find\("abcd\\t\\n","%c%c"\)|5 6|
|%C|非控制字符|string.find\("\\t\\nabcd","%C%C"\)|3 4|
|%d|数字|string.find\("abcd12","%d%d"\)|5 6|
|%D|非数字|string.find\("12abcd","%D%D"\)|3 4|
|%x|十六进制数字|string.find\("efgh","%x%x"\)|1 2|
|%X|非十六进制数字|string.find\("efgh","%X%X"\)|3 4|
|%a|字母|string.find\("AB12","%a%a"\)|1 2|
|%A|非字母|string.find\("AB12","%A%A"\)|3 4|
|%l|小写字母|string.find\("ABab","%l%l"\)|3 4|
|%L|大写字母|string.find\("ABab","%L%L"\)|1 2|
|%u|大写字母|string.find\("ABab","%u%u"\)|1 2|
|%U|非大写字母|string.find\("ABab","%U%U"\)|3 4|
|%w|字母和数字|string.find\("a1\(\)","%w%w"\)|1 2|
|%W|非字母非数字|string.find\("a1\(\)","%W%W"\)|3 4|


## 转义字符%

|字符类|描述|示例|结果|
|------|----|----|----|
|%|转义字符|string.find\("abc%..","%%"\)|4 4|
|||string.find\("abc..d","%.%."\)|4 5|


## 用\[\]创建字符集，"-"为连字符，"^"表示字符集的补集

|字符类|描述|示例|结果|
|------|----|----|----|
|\[01\]|匹配二进制数|string.find\("32123","\[01\]"\)|3 3|
|\[AB\]\[CD\]|匹配AC、AD、BC、BD|string.find\("ABCDEF","\[AB\]\[CD\]"\)|2 3|
|\[\[\]\]|匹配一对方括号\[\]|string.find\("ABC\[\]D","\[\[\]\]"\)|4 5|
|\[1-3\]|匹配数字1-3|string.find\("312","\[1-3\]\[1-3\]\[1-3\]"\)|1 3|
|\[b-d\]|匹配字母b-d|string.find\("dbc","\[b-d\]\[b-d\]\[b-d\]"\)|1 3|
|\[^%s\]|匹配任意非空字符|string.find\(" a ","\[^%s\]"\)|3 3|
|\[^%d\]|匹配任意非数字字符|string.find\("123a","\[^%d\]"\)|4 4|
|\[^%a\]|匹配任意非字母字符|string.find\("abc1","\[^%a\]"\)|4 4|


## 用"\(\)"进行捕获

|字符类|描述|示例|结果|
|------|----|----|----|
|\(\)|捕获字符串|string.find\("12ab","\(%a%a\)"\)|3 4 ab|
|||string.find\("ab12","\(%d%d\)"\)|3 4 12|


## 模式修饰符

|修饰符|描述|示例|结果|
|------|----|----|----|
|\+|表示1个或多个，匹配最多个|string.find\("aaabbb","\(a\+b\)"\)|1 4 aaab|
|||string.find\("cccbbb","\(a\+b\)"\)|nil|
|-|表示0个或多个，匹配最少个|string.find\("zzxyyy","\(xy-\)"\)|3 3 x|
|||string.find\("zzzyyy","\(x-y\)"\)|4 4 y|
|\*|表示0个或多个，匹配最多个|string.find\("mmmnnn","\(m\*n\)"\)|1 4 mmmn|
|||string.find\("lllnnn","\(m\*n\)"\)|4 4 n|
|?|表示0个或1个|string.find\("aaabbb","\(a?b\)"\)|3 4 ab|
|||string.find\("cccbbb","\(a?b\)"\)|4 4 b|


## match 的常见用法

|描述|示例|结果|
|----|----|----|
|匹配中文|string.match\("男女abc123","\([^%w%p]\+\)"\)|男女|
|匹配英文|string.match\("男女abc123","\(%a\+\)"\)|abc|
|匹配数字|string.match\("男女abc123","\(%d\+\)"\)|123|
|匹配英文和数字|string.match\("男女abc123","\(%w\+\)"\)|abc123|

---

Source: [产生一个随机数 (sys.rnd)](https://xxtouch.app/docs/handbook/sys/sys.rnd.md)
Path: handbook/sys/sys.rnd.md

# 产生一个随机数 (sys.rnd)


## 声明

```lua
随机数字 = sys.rnd()
```


## 返回值

- 随机数字
    整数型，返回一个随机数字，范围 0~4294967295


## 说明

> 产生一个真随机数


## 示例

```lua
math.randomseed(sys.rnd()) -- 初始化随机因子为一个真随机数
local r = math.random(1, 100) -- 产生一个 1~100 范围的随机数
```

---

Source: [! 毫秒级延迟 (:msleep)](https://xxtouch.app/docs/handbook/touch/touchm_msleep.md)
Path: handbook/touch/touchm_msleep.md

# ! 毫秒级延迟 (:msleep)


## 声明

```lua
触摸事件 = 触摸事件:msleep(毫秒数)
```


## 参数

- 毫秒数
    实数型，可选参数，延迟时间，单位毫秒，默认 0.1


## 返回值

- 触摸事件
    触摸事件对象本体，通过调用 [touch.on](/docs/handbook/touch/touch.on.md) 函数可以获得一个用于操控当前触摸的事件对象


## 说明

> 延迟函数，不会对对象产生影响，仅起阻塞当前线程的作用。该方法的别名为 :delay
> **该方法可能会让出，在其返回之前，其他 [线程](/docs/handbook/thread/index.md) 可能会得到运行机会**


## 示例

```lua
-- 模拟一个手指于点 100, 100 的位置接触屏幕，等待 300 毫秒，离开屏幕
touch.on(100, 100):msleep(300):off()
```

---

Source: [生成基于时间的一次性验证码 (utils.totp_next)](https://xxtouch.app/docs/handbook/utils/utils.totp_next.md)
Path: handbook/utils/utils.totp_next.md

# 生成基于时间的一次性验证码 (utils.totp_next)


## 声明

```lua
验证码, 错误信息 = utils.totp_next(时间戳, 链接[, 密钥])
```


## 参数

- 时间戳
    整数型，Unix 时间戳，单位为秒；传入 -1 表示使用当前时间
- 链接
    文本型，TOTP 链接，格式为 `otpauth://totp/...`
- 密钥
    文本型，Base32 格式，可选参数；传入后将使用该密钥生成验证码


## 返回值

- 验证码
    文本型，生成的一次性验证码
- 错误信息
    文本型，生成失败时返回错误信息


## 说明

> **该函数在 20260107 以后版本方可使用**
> 根据 TOTP 链接生成当前时间对应的一次性验证码
> 链接中通常需要包含 `secret`，可选包含 `digits`、`period`、`algorithm`
> `algorithm` 可使用 `SHA1`、`SHA256` 或 `SHA512`


## 示例

```lua
local url = "otpauth://totp/Demo:alice?secret=JBSWY3DPEHPK3PXP&issuer=Demo&digits=6&period=30&algorithm=SHA1"

local code, err = utils.totp_next(-1, url)
if code then
    nLog(code)
else
    nLog(err)
end
```

---

Source: [设置配置界面上的某个控件的值 (xui.set)](https://xxtouch.app/docs/handbook/xui/xui.set.md)
Path: handbook/xui/xui.set.md

# 设置配置界面上的某个控件的值 (xui.set)


## 声明

```lua
操作成败 = xui.set(配置分区, 配置键, 值)
```


## 参数

- 配置分区
    文本型，配置界面中的配置分区（defaults）标识符
- 配置键
    文本型，配置界面中的控件的配置键（key）标识符
- 值
    任意类型，不同的控件类型可以设置不同的值


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false


## 说明

> 若当前正显示着配置界面，该函数会立刻更新界面上的显示值
> 该函数不会过滤值类型；如需保证值类型合法，可于设置后使用 `xui.setup` 校验修正
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.set('com.yourcompany.A-Script-Bundle', 'enabled', true)
xui.setup('interface.xui')
```

---

Source: [检测应用程序是否正在运行 (app.is_running)](https://xxtouch.app/docs/handbook/app/app.is_running.md)
Path: handbook/app/app.is_running.md

# 检测应用程序是否正在运行 (app.is_running)


## 声明

```lua
状态 = app.is_running(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 状态
    布尔型，是否正在运行


## 说明

> 本函数用于检查一个应用程序是否正在运行，它不区分前后台
> 如需判断应用是否在前台运行，可使用 [`app.front_bid`](/docs/handbook/app/app.front_bid.md) 获取前台应用 bid 后进行对比，如下
```lua
if "com.tencent.mqq" == app.front_bid() then
    sys.alert('QQ 正在前台运行')
end
```
> **注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 示例

```lua
if app.is_running("com.tencent.mqq") then
    sys.alert('QQ 正在运行')
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [ML 多维数组模块](https://xxtouch.app/docs/handbook/coreml/coreml.multi_array_module.md)
Path: handbook/coreml/coreml.multi_array_module.md

# ML 多维数组模块

`MLMultiArray` 是 CoreML 里最常见的张量类型。
这页统一说明 `coreml` 模块中与 `MLMultiArray` 相关的模块级函数和对象方法，包括：

- 创建张量
- 把 Lua / 图像 / OpenCV 数据转成张量
- `MLMultiArray` 与 ORT tensor 互转
- 常用数学运算、归约、排序和拼接
- 检测 / OBB / mask / keypoint / tracker 等后处理辅助

如果你要在 Lua 层封装分类、Embedding、文本模型、检测模型或其它通用 CoreML 模型，这一页里的能力就是主要基础。

> **该模块在 20260319 以后版本方可使用**

## 创建与转换

### `coreml.new_multi_array(opts)` / `coreml.tensor(opts)`

```lua
多维数组对象, 错误信息 = coreml.new_multi_array({
    shape = 形状数组,
    data_type = 数据类型,
})
```

用于创建一个空的 CoreML 多维数组对象，适合后续作为模型输入或中间张量使用。

- `shape` 为目标形状，例如 `{1, 3, 224, 224}`
- `data_type` 可选 `"int32"`、`"float32"`、`"float16"`、`"double"`；`"float64"` 可作为 `"double"` 的别名
- `coreml.tensor(opts)` 是同义别名

### `coreml.multi_array_from_table(data, opts)` / `coreml.tensor_from_table(data, opts)`

```lua
多维数组对象, 错误信息 = coreml.multi_array_from_table(数据表, {
    shape = 形状数组,
    data_type = 数据类型,
})
```

用于把 Lua 表中的数据显式转换成 `MLMultiArray`。

- `shape` 必须与数据总量匹配
- `data_type` 规则与 `new_multi_array()` 一致
- `coreml.tensor_from_table(...)` 是同义别名

### `coreml.tensor_from_image(image[, opts])`

```lua
多维数组对象, 元信息 = coreml.tensor_from_image(图片, 配置)
```

用于把图片对象按显式配置转换为 CoreML 可用的张量。

常用配置字段：

- `width` / `height`
- `layout`：仅支持 `"nchw"`、`"nhwc"`
- `channel_order`：`"rgb"`、`"bgr"`、`"gray"`、`"grey"` 或 `"grayscale"`
- `data_type`
- `scale`
- `mean`
- `std`
- `resize_mode`：`"stretch"`、`"letterbox"`、`"center_crop"`
- `letterbox_mode`：支持 `"center"`、`"top_left"`，其中 `"topleft"` 也会按 `"top_left"` 处理
- `pad_color`
- `interpolation`：`"bilinear"`、`"nearest"`
- `alpha_mode`：`"ignore"`、`"white"`、`"black"`、`"premultiply"`
- `crop = {x, y, width, height}`

说明：

- 该函数只负责显式配置驱动的图像张量化，不会隐式绑定某个具体模型的预处理规则
- 成功时第二个返回值是预处理元信息表；失败时返回 `nil, 错误信息`
- 元信息常见字段包括：
  `src_width`、`src_height`、`crop_x`、`crop_y`、`crop_width`、`crop_height`、`dst_width`、`dst_height`、`resized_width`、`resized_height`、`scale_x`、`scale_y`、`ratio`、`pad_left`、`pad_top`、`pad_right`、`pad_bottom`、`resize_mode`、`offset_x`、`offset_y`、`letterbox_mode`

### `coreml.tensor_from_images(images[, opts])`

```lua
批量张量, 批量元信息 = coreml.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})
```

把一组图像批量转换成 `MLMultiArray`。

- 原图尺寸可以不同
- 只要每张图解析后的输出 shape 与 `data_type` 一致，就能拼成 batch
- 第二个返回值是与输入顺序对应的元信息数组

### `coreml.image_from_tensor(tensor[, opts])`

```lua
图像对象, 错误信息 = coreml.image_from_tensor(张量, opts)
```

把 2D / 3D / 4D `MLMultiArray` 还原成图像对象，适合调试模型输入输出。

常用配置字段：

- `layout`
- `channel_order`
- `batch_index`：1-based，默认第 `1` 个 batch
- `scale`
- `mean`
- `std`
- `clamp`
- `value_range`：`"0_255"` 或 `"0_1"`

说明：

- 仅支持 2D / 3D / 4D 张量
- 通道数仅支持 `1` 或 `3`

### `coreml.image_to_multi_array(image[, opts])`

这是旧接口名，当前只是 `coreml.tensor_from_image(...)` 的兼容别名。新代码建议统一使用 `tensor_from_image()`。

### `coreml.tensor_from_cv_mat(mat[, opts])` / `coreml.multi_array_from_cv_mat(mat[, opts])`

用于把 `cv.mat` 转成 `MLMultiArray`。

- 需要先 `require("image.cv")`
- 两个名字是同义别名

### `coreml.tensor_from_quad(mat, quad[, opts])` / `coreml.multi_array_from_quad(mat, quad[, opts])`

```lua
多维数组对象, 错误信息 = coreml.tensor_from_quad(mat, {
    {x = 0, y = 0},
    {x = 100, y = 0},
    {x = 100, y = 32},
    {x = 0, y = 32},
}, {
    width = 100,
    height = 32,
    layout = "hwc",
    channel_order = "rgb",
    data_type = "float32",
})
```

用于从 `cv.mat` 中按四边形区域做透视裁剪，再直接得到 `MLMultiArray`。

- 需要先 `require("image.cv")`
- `quad` 可以直接传四个点，也可以传带 `points` 字段的表
- 常用 `opts` 与 `tensor_from_image()` 基本一致，额外常见字段有 `content_width`、`content_height`、`border_type`
- 适合 OCR 识别前的单框拉正与张量化

### `coreml.tensor_from_quads(mat, quads[, opts])` / `coreml.multi_array_from_quads(mat, quads[, opts])`

```lua
批量张量, 错误信息 = coreml.tensor_from_quads(mat, {
    {
        points = quad1,
        content_width = 96,
        content_height = 32,
    },
    {
        points = quad2,
        content_width = 80,
        content_height = 32,
    },
}, {
    width = 96,
    height = 32,
    resize_mode = "top_left_letterbox",
    border_type = "replicate",
})
```

用于批量裁剪多个四边形并自动拼成 batch 张量。

- 需要先 `require("image.cv")`
- `quads` 必须是非空数组；每项可以带 `points`
- 每项里的 `content_width`、`content_height` 会覆盖全局 `opts` 里的同名字段
- 返回值会按结果 rank 自动走 `stack()` 或 `concat()` 拼成 batch，适合 OCR 多框批处理

### `coreml.multi_array_from_ort_tensor(tensor[, data_type])`

```lua
多维数组对象, 错误信息 = coreml.multi_array_from_ort_tensor(ORT张量[, "float32"])
```

用于把 `onnxruntime.tensor` 原生拷贝成 `MLMultiArray`。

- 这个函数默认不存在；只有执行过 `require("onnxruntime")` 后才会被注入到内置 `coreml` 模块中
- 转换过程走 native 层拷贝，不经过 Lua table
- `string` tensor 不能转换成 `MLMultiArray`

## 类型判断与别名

### `coreml.is_multi_array(value)` / `coreml.is_tensor(value)`

```lua
是否多维数组 = coreml.is_multi_array(需要判断的值)
```

用于判断一个值是否为 `coreml_multi_array_object`。`is_tensor()` 是同义别名。

## 模块级辅助函数

### 基础张量辅助

- `coreml.concat(arrays, axis)`
- `coreml.stack(arrays, axis)`
- `coreml.gather(array, dim, indices)`
- `coreml.take(array, indices[, dim])`
- `coreml.gather_rows(array, indices)`
- `coreml.clamp(array, min, max)`
- `coreml.sigmoid(array)`
- `coreml.exp(array)`
- `coreml.where(condition, x, y)`
- `coreml.matmul(lhs, rhs)`

说明：

- `take()` 默认沿第 `1` 维取值
- `gather_rows()` 是 `take(array, indices, 1)` 的便捷别名
- `where()` 支持标量与 `MLMultiArray` 混用，并按广播规则生成结果
- `matmul()` 当前支持 rank-1 / rank-2 输入组合

### 几何与检测辅助

- `coreml.nms(boxes, scores[, opts])`
- `coreml.box_points(rotated_boxes)`
- `coreml.xywh_to_xyxy(boxes)`
- `coreml.xyxy_to_xywh(boxes)`
- `coreml.rotated_iou(lhs, rhs)`
- `coreml.rotated_nms(boxes, scores[, opts])`

说明：

- `nms()` 的 `boxes` 必须是 `[N, 4]`，`scores` 必须是 `[N]` 或 `[N, C]`
- `rotated_nms()` 的 `boxes` 必须是 `[N, 5]`；当前 `scores` 使用 Lua 数字数组
- 两者返回的都是保存 **1-based** 索引的 `MLMultiArray`

### 解码与 record 辅助

- `coreml.create_decoder(schema)`
- `coreml.decode_yolo(output[, opts])`
- `coreml.decode_yolo_obb(output[, opts])`
- `coreml.decode_matrix_candidates(output, schema[, opts])`
- `coreml.decode_dense_detection(output, opts)`
- `coreml.records_from_boxes(boxes, scores, class_ids[, keep_indices])`
- `coreml.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])`
- `coreml.points_to_records(points[, opts])`

说明：

- `create_decoder()` 返回 decoder 对象，支持 `:decode()`、`:task()`、`:schema()`
- `decode_dense_detection()` 返回 `{ boxes, scores, labels }`，当输入是 batch 时返回 batch 结果数组
- `decode_dense_detection()` 的 `opts.strides` 是必填项，且必须是非空正整数数组
- `decode_dense_detection()` 还要求 `decode_width`、`decode_height`，且当前只支持 `box_encoding = "grid_center_log_wh"`
- `records_from_boxes()`、`obb_records_from_rows()`、`points_to_records()` 会把张量结果整理成更适合 Lua 使用的 record table

### 掩码、关键点与跟踪辅助

- `coreml.threshold_masks(masks, threshold)`
- `coreml.crop_masks_by_boxes(masks, boxes)`
- `coreml.resize_masks(masks, width, height[, opts])`
- `coreml.mask_iou(lhs_mask, rhs_mask)`
- `coreml.mask_to_polygon(mask[, opts])`
- `coreml.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])`
- `coreml.project_masks(proto, coeffs, boxes, image_width, image_height[, opts])`
- `coreml.db_postprocess(score_map[, opts])`
- `coreml.tracker([opts])`
- `coreml.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])`
- `coreml.scale_boxes(boxes, transform)`
- `coreml.clip_boxes(boxes, clip_width, clip_height)`
- `coreml.scale_points(points, transform[, opts])`
- `coreml.scale_keypoints(points, transform[, opts])`
- `coreml.clip_keypoints(points, clip_width, clip_height[, opts])`
- `coreml.ctc_greedy_decode(logits[, opts])`
- `coreml.sample_logits(logits[, opts])`

说明：

- `project_masks()` 是 `proto_masks()` 的别名
- `mask_iou()` 用于直接计算两张 mask 的交并比
- `mask_iou()` 还支持第三个参数 `opts`，可传 `compare_size = true`，或显式传 `width` / `height` 作为对齐后的比较尺寸
- `db_postprocess()` 适合 DB / DBNet 一类文本检测后处理；输入支持 `[H, W]`、`[C, H, W]` 或 `[N, C, H, W]`
- `db_postprocess()` 返回检测数组，每项都带 `score`、`points` 和 `box`；`meta` / `image_meta` 可直接复用图像张量化返回的元信息
- `tracker()` 返回跟踪器对象，支持 `:update()`、`:reset()`、`:state()`、`:close()`
- `ctc_greedy_decode()` 输入支持 `[T, C]` 或 `[N, T, C]`
- `ctc_greedy_decode()` 支持 `blank_index`、`merge_repeated`、`apply_softmax`、`return_probabilities`、`charset`
- `ctc_greedy_decode()` 一定会返回 `indices`；只有传了 `charset` 才会带 `text`；只有启用 `apply_softmax` 或 `return_probabilities` 才会带 `confidence`；只有启用 `return_probabilities` 才会额外带 `probabilities` 和 `probability_confidence`
- `sample_logits()` 支持 `argmax`、`temperature`、`top_k`、`top_p`、`min_p`、`seed`
- `sample_logits()` 对 1D logits 返回单个 **1-based** 索引；对 batched logits 返回索引 `MLMultiArray`

## 对象基础方法

### 基础查询

- `array:shape()`
- `array:data_type()`
- `array:count()`
- `array:strides()`
- `array:to_table()`
- `array:to_cv_mat([opts])`

说明：

- `data_type()` 返回 `"int32"`、`"float32"`、`"float16"` 或 `"double"`
- `to_cv_mat()` 需要先 `require("image.cv")`

### ORT 桥接

- `array:to_ort_tensor([data_type])`

这个方法默认不存在；只有执行过 `require("onnxruntime")` 后才会被注入到 `coreml_multi_array_object`。

## 类型与形状变换

- `array:astype(data_type)`
- `array:clone()`
- `array:reshape(shape)`
- `array:transpose(axes)`
- `array:slice(dim, start, stop[, step])`
- `array:select(dim, index)`
- `array:squeeze([dim])`
- `array:unsqueeze(dim)`
- `array:flatten([start_dim[, end_dim]])`

说明：

- `reshape()`、`transpose()`、`squeeze()`、`unsqueeze()`、`flatten()` 默认返回 view，不复制底层数据
- `reshape()` / `flatten()` 对非连续布局会报错；这时可先 `clone()`
- `slice()` 和 `select()` 返回新的连续张量，不是 view
- `slice()` / `select()` / `gather()` / `take()` 的索引语义都与 ONNX 页保持 **1-based** 一致

## 数值与索引方法

- `array:gather(dim, indices)`
- `array:take(indices[, dim])`
- `array:l2_norm()`
- `array:dot(other)`
- `array:max([axis])`
- `array:min([axis])`
- `array:add(other)`
- `array:sub(other)`
- `array:mul(other)`
- `array:div(other)`
- `array:clamp(min, max)`
- `array:sigmoid()`
- `array:exp()`
- `array:matmul(other)`
- `array:scale(number)`

说明：

- `add/sub/mul/div` 支持标量和有限 broadcasting
- `sigmoid()`、`exp()`、`matmul()` 的结果会提升到浮点输出

## 归约、排序与选择

- `array:sum([axis])`
- `array:mean([axis])`
- `array:softmax([axis])`
- `array:normalize([axis])`
- `array:argmax([axis])`
- `array:topk(k[, axis])`
- `array:sort([axis[, descending]])`

说明：

- `argmax()` 不传轴时返回整个数组最大值的 **1-based** 线性索引
- `argmax(axis)` 返回保存索引的 `MLMultiArray`
- `topk()` 返回 `{ values = 张量, indices = 张量 }`
- `sort()` 返回排序后的新 `MLMultiArray`，**不会** 额外返回索引表

## 几何与后处理对象方法

- `array:clip_boxes(clip_width, clip_height)`
- `array:xywh_to_xyxy()`
- `array:xyxy_to_xywh()`
- `array:reshape_keypoints([keypoint_count[, keypoint_dim|opts]])`
- `array:scale_points(transform[, opts])`
- `array:clip_keypoints(clip_width, clip_height[, opts])`

这些方法与同名模块级函数共享同一套底层实现，只是把当前数组作为第一个参数传入。

## 使用建议

- 对新的通用 CoreML 接口来说，`MLMultiArray` 是默认的一等数据类型，不建议过早转换为 Lua 表
- 大多数批量运算应尽量在张量对象上完成，只有在调试、小数据输出或兼容旧代码时再调用 `to_table()`
- 图像预处理规则应通过 `tensor_from_image()` 的参数显式指定，避免把某个模型的预处理硬编码到通用流程中
- 如果你需要一份独立副本，或希望把非连续布局整理成连续张量，请显式调用 `clone()`

## 示例

```lua
local arr = assert(coreml.tensor({
    shape = {2, 3},
    data_type = "float32",
}))

local filled = assert(coreml.tensor_from_table({
    {1, 2, 3},
    {4, 5, 6},
}, {
    shape = {2, 3},
    data_type = "float32",
}))

local merged = assert(coreml.concat({filled, filled}, 1))
print(coreml.is_tensor(merged))
print(merged:shape())
```

---

Source: [振动设备 (device.vibrator)](https://xxtouch.app/docs/handbook/device/device.vibrator.md)
Path: handbook/device/device.vibrator.md

# 振动设备 (device.vibrator)


## 声明

```lua
device.vibrator()
```


## 说明

> 让设备振动一次（没有振动马达的设备不支持此功能）


## 示例

```lua
device.vibrator()
```

---

Source: [给对话框加上一个文本输入框 (:add_input)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_input.md)
Path: handbook/dialog/dialogm_add_input.md

# 给对话框加上一个文本输入框 (:add_input)


## 声明

```lua
对话框对象 = 对话框对象:add_input(输入框标签 [, 输入框默认内容 ])
```


## 参数

- 输入框标签
    文本型，文本框左侧标签显示的文本
- 输入框默认内容
    文本型 或 实数型，文本框中的默认值

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    文本型，返回用户输入的内容


## 说明

> 给对话框加上一个文本输入框


## 示例

```lua
local c, s = dialog():add_input('一个输入框', '默认内容'):show()
sys.alert('输入的内容是：'..s['一个输入框'])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [设置文本文件指定行的内容 (file.set_line)](https://xxtouch.app/docs/handbook/file/file.set_line.md)
Path: handbook/file/file.set_line.md

# 设置文本文件指定行的内容 (file.set_line)


## 声明

```lua
写入成败, 错误信息 = file.set_line(文件路径, 行号, 待写入内容)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行号
    整数型，指定行号，0 为最后一行 \+1，负数则为倒数行号
- 待写入内容
    字符串型，需要设置为指定行的数据

## 返回值

- 写入成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 设置文本文件指定行的内容，行数不够用空行补足，文件不存在会创建文件，目录不存在会返回 false
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local success, err = file.set_line("/var/mobile/1.txt", 3, "哈哈哈")
if success then
    sys.alert("操作成功")
else
    sys.alert("操作失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取手柄设备属性 (:get_properties)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_get_properties.md)
Path: handbook/gamepad/gamepadm_get_properties.md

# 获取手柄设备属性 (:get_properties)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
属性 = 手柄对象:get_properties()
```

## 返回值

- 属性
    表型，创建设备时保存的配置属性副本

## 说明

- 返回的是创建该手柄时保存的配置副本，其中可能包含由系统管理的属性
- 返回值不代表系统最终采用的值，请勿用它判断目标 App 是否已经识别手柄
- 脚本只应依赖自己传入或文档列出的字段

## 示例

```lua
local pad = assert(gamepad.connect())

local properties = pad:get_properties()
print(properties.Product)
print(properties.Transport)
assert(pad:disconnect())
```

---

Source: [保存图片对象到相册 (:save_to_album)](https://xxtouch.app/docs/handbook/image/imagem_save_to_album.md)
Path: handbook/image/imagem_save_to_album.md

# 保存图片对象到相册 (:save_to_album)


## 声明

```lua
图片:save_to_album()
```


## 说明

> 导出图片对象的图片到系统相册


## 示例 1

```lua
-- 从网上下载个小图片直接转存到相册
local c, h, r = http.get("https://www.xxtouch.app/img/Logo.png", 10)
if (c == 200) then
    local img = image.load_data(r)
    img:save_to_album()
    sys.alert("图片已存到相册")
else
    sys.alert("下载失败")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`http.get`](/docs/handbook/http/http.get.md)


## 示例 2

```lua
-- 截全屏图片保存到相册
screen.image():save_to_album()
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)


## 示例 3

```lua
-- 将文件转存到相册 (这只是例子，文件不存在会报错，请在保存之前先做判断)
image.load_file("/var/mobile/1.png"):save_to_album()
```


## 示例 4

```lua
-- 将文件转存到相册
img = image.load_file("/var/mobile/1.png")
if image.is(img) then
    img:save_to_album()
end
```

---

Source: [断开全局硬件键盘 (key.disconnect_global_keyboard)](https://xxtouch.app/docs/handbook/key/key.disconnect_global_keyboard.md)
Path: handbook/key/key.disconnect_global_keyboard.md

# 断开全局硬件键盘 (key.disconnect_global_keyboard)

> **该函数在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = key.disconnect_global_keyboard()
```

## 返回值

- 是否成功
    布尔型，断开成功或当前没有全局硬件键盘时返回 `true`；失败时返回 `false`。
- 错误信息
    文本型，断开失败时返回错误信息。

## 说明

> 释放全部按键并断开当前全局硬件键盘。断开后，原有按键接口恢复连接前的行为。

- 本函数可以重复调用；当前没有全局硬件键盘时也返回成功。
- 全局硬件键盘正在执行 `:press` 或 `:send_text` 序列时，断开会返回 `false, "hardware keyboard is busy"`。
- 已经由 `key.down` 按下的按键会在断开时释放；之后对应的 `key.up` 不会再次发送输入。

## 示例

```lua
local success, err = key.disconnect_global_keyboard()
assert(success, err)
```

---

Source: [断开硬件鼠标 (:disconnect)](https://xxtouch.app/docs/handbook/mouse/mousem_disconnect.md)
Path: handbook/mouse/mousem_disconnect.md

# 断开硬件鼠标 (:disconnect)

> **该方法在 20260805 以后版本方可使用**


## 声明

```lua
状态, 错误信息 = 鼠标对象:disconnect()
```


## 返回值

- 状态
    布尔型，断开成功返回 `true`，失败返回 `false`
- 错误信息
    文本型，断开失败的原因


## 说明

> 释放全部鼠标按键并断开对象。该方法可以重复调用。
> 显式断开、Lua 回收鼠标对象或脚本停止时，XXTouch 都会自动释放全部鼠标按键。
> 即使释放按键失败，对象仍会断开，并且不会自动改用触摸事件。


## 示例

```lua
local m = assert(mouse.connect())
local ok, err = m:disconnect()
assert(ok, err)
```

---

Source: [lua-openssl 扩展库](https://xxtouch.app/docs/handbook/open-source/lua-openssl.md)
Path: handbook/open-source/lua-openssl.md

# lua-openssl 扩展库

[lua-openssl 手册地址](https://zhaozg.github.io/lua-openssl/index.html)

[lua-openssl GitHub 仓库](https://github.com/zhaozg/lua-openssl)

---

XXTouch 已内建 [zhaozg/lua-openssl](https://github.com/zhaozg/lua-openssl)，可直接通过 `require("openssl")` 使用。

```lua
local openssl = require("openssl")
```

## AES-128-ECB 示例

```lua
local cipher = require("openssl").cipher

local key = "1234567890abcdef" -- AES-128 需要 16 字节密钥
local plaintext = "hello xxtouch"

local encrypted = assert(cipher.encrypt("aes-128-ecb", plaintext, key))
local decrypted = assert(cipher.decrypt("aes-128-ecb", encrypted, key))

assert(decrypted == plaintext)
```

## AES-128-CBC 示例

```lua
local cipher = require("openssl").cipher

local key = "1234567890abcdef" -- AES-128 需要 16 字节密钥
local iv = "abcdef1234567890"  -- AES-128-CBC 需要 16 字节 IV
local plaintext = "hello xxtouch"

local encrypted = assert(cipher.encrypt("aes-128-cbc", plaintext, key, iv))
local decrypted = assert(cipher.decrypt("aes-128-cbc", encrypted, key, iv))

assert(decrypted == plaintext)
```

## AES-128-GCM 示例

```lua
local openssl = require("openssl")
local cipher = openssl.cipher

local evp = assert(cipher.get("aes-128-gcm"))
local key = openssl.random(16)
local iv = openssl.random(12)
local aad = "xxtouch"
local plaintext = "hello xxtouch"
local tag_len = 16

local enc = assert(evp:encrypt_new())
assert(enc:ctrl(cipher.EVP_CTRL_GCM_SET_IVLEN, #iv))
assert(enc:init(key, iv))
assert(enc:update(aad, true))
local encrypted = assert(enc:update(plaintext))..assert(enc:final())
local tag = assert(enc:ctrl(cipher.EVP_CTRL_GCM_GET_TAG, tag_len))

local dec = assert(evp:decrypt_new())
assert(dec:ctrl(cipher.EVP_CTRL_GCM_SET_IVLEN, #iv))
assert(dec:init(key, iv))
assert(dec:update(aad, true))
local decrypted = assert(dec:update(encrypted))
assert(dec:ctrl(cipher.EVP_CTRL_GCM_SET_TAG, tag))
decrypted = decrypted..assert(dec:final())

assert(decrypted == plaintext)
```

---

Source: [向进程队列词典尾部压入一个值 (proc_queue_push_back)](https://xxtouch.app/docs/handbook/proc/proc_queue_push_back.md)
Path: handbook/proc/proc_queue_push_back.md

# 向进程队列词典尾部压入一个值 (proc_queue_push_back)


## 声明

```lua
尺寸 = proc_queue_push_back(键, 值)
```


## 参数

- 键
    字符串型
- 值
    字符串型，代表需要压入的值

## 返回值

- 尺寸
    整数型，压入值之后，返回该队列的尺寸，如果返回 0 ，则为压入失败


## 说明

> **此函数效果等同 [proc_queue_push](/docs/handbook/proc/proc_queue_push.md)**
> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> **进程队列词典的队列尺寸不能大于 10000，尺寸超过的队列将丢弃最先压入的值**
> 往进程队列词典尾部压入一个值，压入值之后，返回该队列的尺寸
> 不能压入空字符串


## 示例

```lua
local size = proc_queue_push_back("billnos", "name")
if size ~= 0 then
    print("has "..size.." bill(s)")
else
    print("failed")
end
```

---

Source: [多点色偏模式找色 (screen.find_color)](https://xxtouch.app/docs/handbook/screen/screen.find_color-co.md)
Path: handbook/screen/screen.find_color-co.md

# 多点色偏模式找色 (screen.find_color)


## 声明

```lua
横坐标, 纵坐标 = screen.find_color({
    [find_all = 是否搜索多个结果,]
    [max_results = 最大结果数,]
    [max_miss = 允许最多未命中数,]
    {起始点横坐标, 起始点纵坐标, {起始点颜色[, 起始点色偏]}},
    {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}},
    {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}},
    ...
} [, 左, 上, 右, 下 ])
```

## 参数

- 是否搜索多个结果
    布尔型，可选参数，这个标签设置为 true 会返回范围内所有匹配位置的一个表，格式为 \{\{x1, y1\}, \{x2, y2\}, ...\}，默认 false
- 最大结果数
    整数型，可选参数，当 find_all \(是否搜索多个结果\)  标签设置为 true 的时候，这个表示最多返回结果数，最多可以设为 1000，默认 100
- 允许最多未命中数
    整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算找到
- 起始点横坐标, 起始点纵坐标
    整数型，代表起始坐标，它并不是限制找色的范围为固定这一点，而仅仅是给偏移位置一个相对坐标。若不需要使用偏移，可填 0, 0
- 起始点颜色
    整数型，代表需要搜索的那一点的颜色
- 起始点色偏
    整数型，需要搜索的颜色的最大色偏 \(或偏色\) ，大于 0xff000000 则为反匹配模式
- 偏移点横坐标\*, 偏移点纵坐标\*
    整数型，代表一个偏移位置坐标
- 偏移点颜色\*
    整数型，代表偏移位置需要匹配的颜色
- 偏移点色偏\*
    整数型，偏移位置的颜色的色偏 \(或偏色\) ，大于 0xff000000 则为反匹配模式
- 左, 上, 右, 下
    整数型，可选参数，代表搜索区域，默认 全屏


## 返回值

- 横坐标, 纵坐标
    整数型，返回匹配色的第一个色的坐标，搜索失败返回 -1, -1


## 说明

> 使用色偏（或偏色）模式查找，获取区域中第一个完全匹配的多点颜色结构的位置
> 当前函数坐标值参数及返回值均受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> **色偏（或偏色）** 通常用于表示某个颜色范围，一个颜色附带色偏（或偏色）是指该颜色的红、绿、蓝偏移范围内的所有颜色
当 0x456789 色偏为 0x123456 的时候表示 0x456789 的红正负范围 0x12、绿正负范围 0x34、蓝正负范围 0x56
也就是其红色范围为 0x45 ± 0x12、绿色范围为 0x67 ± 0x34、蓝色的范围为 0x89 ± 0x56，如下表所示

|负|正|
|:-|:-|
|0x45 \- 0x12 = 0x33|0x45 \+ 0x12 = 0x57|
|0x67 \- 0x34 = 0x33|0x67 \+ 0x34 = 0x9B|
|0x89 \- 0x56 = 0x33|0x89 \+ 0x56 = 0xDF|
> 上表所述 \{0x456789, 0x123456\} 即表示从 0x333333 到 0x579BDF 范围内的所有颜色
> **使用 0x 开头的数字为 16 进制数**（[什么是 16 进制数?](https://baike.baidu.com/item/%E5%8D%81%E5%85%AD%E8%BF%9B%E5%88%B6%E6%95%B0/5697828)）


## 示例

```lua
x, y = screen.find_color({
    {  0,   0, {0xec1c23, 0x000000}},
    { 12,  -3, {0xffffff, 0x101010}},
    {  5, -18, {0x00adee, 0x123456}},
    { -1, -10, {0xffc823, 0x101001}},
    {  2, -34, {0xa78217, 0x101001}},
    { 12, -55, {0xd0d2d2, 0x101001}},
}, 0, 0, 100, 100)
--
--[[
    在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 完全相似 (色偏为 0)
    且它的相对坐标 (12, -3) 的位置的颜色与 0xffffff 的色偏小于 0x101010
    且它的相对坐标 (5, -18) 的位置的颜色与 0x00adee 色偏小于 0x123456
    且…… (后面的同理) 都能匹配的那个点
--]]
--
-- 等效代码如下：
--
x, y = screen.find_color({
    { 509, 488, {0xec1c23, 0x000000}},
    { 521, 485, {0xffffff, 0x101010}},
    { 514, 470, {0x00adee, 0x123456}},
    { 508, 478, {0xffc823, 0x101001}},
    { 511, 454, {0xa78217, 0x101001}},
    { 521, 433, {0xd0d2d2, 0x101001}},
}, 0, 0, 100, 100)
--
--[[
    在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 完全相似 (色偏为 0)
    且它的相对坐标 (521-509, 485-488) 的位置的颜色与 0xffffff 的色偏小于 0x101010
    且它的相对坐标 (514-509, 470-488) 的位置的颜色与 0x00adee 色偏小于 0x123456
    且…… (后面的同理) 都能匹配的那个点
--]]
--
-- 不换行无缩进就是这个效果：
x, y = screen.find_color({ {0,0,{0xec1c23,0x000000} },{12,-3, {0xffffff,0x101010} },{5,-18, {0x00adee,0x123456} },{-1,-10,{0xffc823,0x101001} },{2,-34,{0xa78217,0x101001} },{12,-55,{0xd0d2d2,0x101001} }, },0,0,100,100)
--
x, y = screen.find_color({ -- 反匹配演示，在 5C 主屏幕运行可获得结果
    { 516,  288, {0xffffff, 0x101010} },
    { 519,  286, {0xffffff, 0x101010} },
    { 521,  289, {0xffffff, 0x101010} },
    { 516,  296, {0xffffff, 0x101010} },
    { 522,  297, {0xffffff, 0x101010} },
    { 520,  295, {0xffffff, 0xff101010} }, -- 这一点颜色与 0xffffff 色差大于 0x101010 才匹配，下同
    { 515,  291, {0xffffff, 0xff101010} },
    { 518,  284, {0xffffff, 0xff101010} },
    { 523,  298, {0xffffff, 0xff101010} },
    { 514,  298, {0xffffff, 0xff101010} },
    { 514,  296, {0xffffff, 0xff101010} },
}) -- 不写区域参数表示全屏找
--
results = screen.find_color({ -- 范围匹配全输出演示
    {  527,  278, {0xde1d26, 0x101010} },
    {  524,  285, {0x007aff, 0x101010} },
    {  555,  292, {0xe4ddc9, 0x101010} },
    {  536,  314, {0xffde02, 0x101010} },
    {  502,  291, {0xffde02, 0x101010} },
    {  502,  283, {0xe4ddc9, 0x101010} },
    find_all = true, -- 带这个标签将返回范围所有匹配的位置的一个表，格式为 { {x1, y1}, {x2, y2}, ...}
}) -- 不写区域参数表示全屏找
```

---

Source: [math 库的相关应用](https://xxtouch.app/docs/handbook/supplement/math-samples.md)
Path: handbook/supplement/math-samples.md

# math 库的相关应用


|函数名|描述|示例|结果|
|------|----|----|----|
|pi|圆周率|math.pi|3.1415926535898|
|abs|取绝对值|math.abs\(-2012\)|2012|
|ceil|向上取整|math.ceil\(9.1\)|10|
|floor|向下取整|math.floor\(9.9\)|9|
|max|取参数最大值|math.max\(2,4,6,8\)|8|
|min|取参数最小值|math.min\(2,4,6,8\)|2|
|x^y|计算 x 的 y 次幂（Lua 5.3 起 `math.pow` 已移除，改用 `^` 运算符）|2^16|65536.0|
|sqrt|开平方|math.sqrt\(65536\)|256.0|
|modf|取整数和小数部分|math.modf\(20.12\)|20 0.12|
|randomseed|设随机数种子|math.randomseed\(os.time\(\)\)||
|random|取随机数|math.random\(5,90\)|5~90|
|rad|角度转弧度|math.rad\(180\)|3.1415926535898|
|deg|弧度转角度|math.deg\(math.pi\)|180.0|
|exp|e的x次方|math.exp\(4\)|54.598150033144|
|log|计算 x 的自然对数|math.log\(54.598150033144\)|4.0|
|log (指定底数)|计算以指定底数的对数（Lua 5.3 起 `math.log10` 已移除，改用 `math.log(x, 10)`）|math.log\(1000, 10\)|3.0|
|frexp|将参数拆成x \* \(2 ^ y\)的形式|math.frexp\(160\)|0.625 8|
|ldexp|计算x \* \(2 ^ y\)|math.ldexp\(0.625,8\)|160.0|
|sin|正弦|math.sin\(math.rad\(30\)\)|0.5|
|cos|余弦|math.cos\(math.rad\(60\)\)|0.5|
|tan|正切|math.tan\(math.rad\(45\)\)|1.0|
|asin|反正弦|math.deg\(math.asin\(0.5\)\)|30.0|
|acos|反余弦|math.deg\(math.acos\(0.5\)\)|60.0|
|atan|反正切|math.deg\(math.atan\(1\)\)|45.0|

---

Source: [获取设备当前内存状态信息 (sys.memory_info)](https://xxtouch.app/docs/handbook/sys/sys.memory_info.md)
Path: handbook/sys/sys.memory_info.md

# 获取设备当前内存状态信息 (sys.memory_info)


## 声明

```lua
内存状态 = sys.memory_info()
```


## 返回值

- 内存状态
    表型，返回的内存状态信息，各字段含义请参考返回值示例


## 示例

```lua
sys.alert(table.deep_dump(sys.memory_info()))
```
**注**：上述代码中使用了非本章函数 [`table.deep_dump`](/docs/handbook/ext-table/table.deep_dump.md)

---

Source: [按计数器生成一次性验证码 (utils.hotp_counter)](https://xxtouch.app/docs/handbook/utils/utils.hotp_counter.md)
Path: handbook/utils/utils.hotp_counter.md

# 按计数器生成一次性验证码 (utils.hotp_counter)


## 声明

```lua
验证码, 错误信息 = utils.hotp_counter(计数器, 链接[, 密钥])
```


## 参数

- 计数器
    整数型，用于生成 HOTP 验证码的计数器
- 链接
    文本型，HOTP 链接，格式为 `otpauth://hotp/...`
- 密钥
    文本型，Base32 格式，可选参数；传入后将使用该密钥生成验证码


## 返回值

- 验证码
    文本型，生成的一次性验证码
- 错误信息
    文本型，生成失败时返回错误信息


## 说明

> **该函数在 20260107 以后版本方可使用**
> 根据指定计数器和 HOTP 链接生成一次性验证码
> 链接中通常需要包含 `secret`，可选包含 `digits`、`algorithm`
> `algorithm` 可使用 `SHA1`、`SHA256` 或 `SHA512`


## 示例

```lua
local url = "otpauth://hotp/Demo:alice?secret=JBSWY3DPEHPK3PXP&issuer=Demo&digits=6&algorithm=SHA1"

local code, err = utils.hotp_counter(1, url)
if code then
    nLog(code)
else
    nLog(err)
end
```

---

Source: [读取某个配置分区所有配置 (xui.read)](https://xxtouch.app/docs/handbook/xui/xui.read.md)
Path: handbook/xui/xui.read.md

# 读取某个配置分区所有配置 (xui.read)


## 声明

```lua
配置 = xui.read(配置分区)
```


## 参数

- 配置分区
    文本型，配置界面中的配置分区（defaults）标识符

## 返回值

- 配置
    表型，这个配置分区所有配置的键值对，如果没有该配置分区，则返回空表


## 说明

> 该函数适合一次性批量读取多个配置
> 该函数不会过滤值类型；如需保证获取的值类型合法，可先使用 `xui.setup` 校验修正再读取
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.setup('interface.xui')
local dict = xui.read('com.yourcompany.A-Script-Bundle')
local enabled = dict['enabled']
```

---

Source: [通过应用程序 bid 获取应用的本地化名字 (app.localized_name)](https://xxtouch.app/docs/handbook/app/app.localized_name.md)
Path: handbook/app/app.localized_name.md

# 通过应用程序 bid 获取应用的本地化名字 (app.localized_name)


## 声明

```lua
本地化名字 = app.localized_name(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 本地化名字
    文本型 或 nil，返回应用的本地化名字，如果应用不存在则返回 nil


## 示例

```lua
local name = app.localized_name("com.tencent.xin")
sys.alert(name) -- 弹出提示 "微信"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [后台播放声音 (device.play_sound)](https://xxtouch.app/docs/handbook/device/device.play_sound.md)
Path: handbook/device/device.play_sound.md

# 后台播放声音 (device.play_sound)


## 声明

```lua
device.play_sound(声音文件路径)
```


## 参数

- 声音文件路径
    文本型，声音文件的绝对路径，支持 mp3、wav、aac 音频格式


## 说明

> 后台播放一段声音
> 该函数不会影响脚本运行，且声音会在脚本停止时自动停止。若需播放完整声音，请确保脚本延迟退出


## 示例

```lua
device.play_sound("/var/mobile/十年.mp3")
sys.msleep(205 * 1000) -- 等待 205 秒 (3分25秒)
```
**注**：上述代码中使用了非本章函数 [`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [给对话框加上一个图片 (:add_image)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_image.md)
Path: handbook/dialog/dialogm_add_image.md

# 给对话框加上一个图片 (:add_image)


## 声明

```lua
对话框对象 = 对话框对象:add_image(图片)
```

## 参数

- 图片
    图片对象，需要添加到对话框的图片

## 返回值

- 对话框对象
    对话框，返回对话框本身


## 说明

> 给对话框加上一个图片


## 示例

```lua
dialog():add_image(screen.image()):show() -- 弹出一张屏幕截图
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [转成 16 进制文本 (string.to_hex)](https://xxtouch.app/docs/handbook/ext-string/string.to_hex.md)
Path: handbook/ext-string/string.to_hex.md

# 转成 16 进制文本 (string.to_hex)


## 声明

```lua
16进制文本 = string.to_hex(数据内容[, 前缀, 后缀])
```


## 参数

- 数据内容
    字符串型，需要转换成 16 进制的字符串
- 前缀
    字符串型，可选参数，每个转换后的字节的前缀，默认 ""
- 后缀
    字符串型，可选参数，每个转换后的字节的后缀，默认 ""

## 返回值

- 16 进制文本
    文本型，返回 16 进制文本


## 说明

> 将字符串（或二进制数据块）转换为可打印的 16 进制文本
> 关键词：图片十六进制、文件十六进制、数据十六进制


## 示例

```lua
-- 示例   1：
sys.alert(string.to_hex('一些数据'))
-- 输出 "e4b880e4ba9be695b0e68dae"
--
-- 示例   2：
sys.alert((string.to_hex('一些数据'):gsub('(..)', '\\x%1')))
-- 输出 "\xe4\xb8\x80\xe4\xba\x9b\xe6\x95\xb0\xe6\x8d\xae"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [在文本文件指定行前插入内容 (file.insert_line)](https://xxtouch.app/docs/handbook/file/file.insert_line.md)
Path: handbook/file/file.insert_line.md

# 在文本文件指定行前插入内容 (file.insert_line)


## 声明

```lua
写入成败, 错误信息 = file.insert_line(文件路径, 行号, 待插入的内容)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行号
    整数型，指定行号，0 为最后一行 \+1，负数则为倒数行号
- 待插入的内容
    字符串型，需要插入到指定行前的数据

## 返回值

- 写入成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 在文本文件指定行前插入内容，行数不够用空行补足，文件不存在会创建文件，目录不存在会返回 false
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local success, err = file.insert_line("/var/mobile/1.txt", 2, "岂因祸福避趋之")
if success then
    sys.alert("操作成功")
else
    sys.alert("操作失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [断开硬件游戏手柄 (:disconnect)](https://xxtouch.app/docs/handbook/gamepad/gamepadm_disconnect.md)
Path: handbook/gamepad/gamepadm_disconnect.md

# 断开硬件游戏手柄 (:disconnect)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
状态, 错误信息 = 手柄对象:disconnect()
```

## 返回值

- 状态
    布尔型，断开成功返回 true，失败返回 false
- 错误信息
    文本型，操作失败时的错误信息

## 说明

- `disconnect` 可以重复调用
- 显式断开、Lua 回收手柄对象或脚本停止时，全部按键会松开，摇杆和方向键会回中，随后手柄断开
- 如果输入发送失败，该手柄会复位并断开
- 手柄操作失败时不会改用键盘、触摸或其它输入方式

## 示例

```lua
local pad = assert(gamepad.connect())

local success, err = pad:disconnect()
assert(success, err)
```

---

Source: [输出图片对象到一个 PNG 格式的文件 (:save_to_png_file)](https://xxtouch.app/docs/handbook/image/imagem_save_to_png_file.md)
Path: handbook/image/imagem_save_to_png_file.md

# 输出图片对象到一个 PNG 格式的文件 (:save_to_png_file)


## 声明

```lua
图像:save_to_png_file(文件路径)
```

## 参数

- 文件路径
    文本型，需要保存到图片文件的绝对路径


## 说明

> 输出图片对象到一个 PNG 格式的文件，扩展名可以不是 PNG


## 示例

```lua
-- 截全屏图像保存到文件
screen.image():save_to_png_file("/var/mobile/1.png")
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)

---

Source: [按下硬件键盘按键 (:down)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_down.md)
Path: handbook/key/hardware_keyboardm_down.md

# 按下硬件键盘按键 (:down)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = 硬件键盘对象:down(按键码)
是否成功, 错误信息 = 硬件键盘对象:down(Usage_Page, Usage_ID)
```

## 参数

- 按键码
    文本型，与 [`key.press`](/docs/handbook/key/key.press.md) 使用同一份按键名称映射。
- Usage Page
    整数型，当前硬件键盘对象只接受 Keyboard/Keypad Usage Page `0x07`。
- Usage ID
    整数型，物理按键编号，不是字符编码。

## 返回值

- 是否成功
    布尔型，发送成功时返回 `true`，失败时返回 `false`。
- 错误信息
    文本型，发送失败时返回错误信息。

## 说明

> 按下一个硬件键盘按键。按下后应调用对应的 [`:up`](hardware_keyboardm_up.md) 释放按键。

- 同一键盘正在执行 `:press` 或 `:send_text` 序列时，本方法返回 `false, "hardware keyboard is busy"`。
- 同一时间最多按住 6 个普通按键，修饰键不计入；超过限制时目标系统无法识别具体按键。
- 发送失败时返回 `false` 和错误信息，不会自动改用其它输入方式重试。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

assert(keyboard:press(0x07, 4))       -- Keyboard A
assert(keyboard:down(0x07, 0xE1))    -- Left Shift
assert(keyboard:up(0x07, 0xE1))

assert(keyboard:disconnect())
```

---

Source: [从进程队列词典头部弹出一个值 (proc_queue_pop_front)](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_front.md)
Path: handbook/proc/proc_queue_pop_front.md

# 从进程队列词典头部弹出一个值 (proc_queue_pop_front)


## 声明

```lua
值 = proc_queue_pop_front(键)
```


## 参数

- 键
    字符串型


## 返回值

- 值
    字符串型，返回弹出的值，如果队列不存在或为空，则返回空字符串


## 说明

> **此函数效果等同 [proc_queue_pop](/docs/handbook/proc/proc_queue_pop.md)**
> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> 从进程队列词典头部弹出一个值
> 如果队列不存在或为空，则弹出一个空字符串


## 示例

```lua
local billno = proc_queue_pop_front("billnos")
if billno ~= "" then
    print(billno)
else
    print("no bill")
end
```

---

Source: [获取屏幕图像 (screen.image)](https://xxtouch.app/docs/handbook/screen/screen.image.md)
Path: handbook/screen/screen.image.md

# 获取屏幕图像 (screen.image)


## 声明

```lua
图像 = screen.image([ 左, 上, 右, 下 ])
```


## 参数

- 左, 上, 右, 下
    整数型，可选参数，代表图像区域，默认 全屏

## 返回值

- 图像
    图片对象，返回一个图片对象，用法参考 [图片对象模块 (image)](/docs/handbook/image/index.md)


## 说明

> 获取屏幕上区域或全部图像
> 当前函数坐标值参数受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> 该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 [image:destroy](/docs/handbook/image/imagem_destroy.md) 方法使用


## 示例

```lua
-- screen.image 的示例代码
--
screen.image():save_to_album() -- 全屏截图并保存到相册
--
screen.image():save_to_png_file("/var/mobile/1.png") -- 全屏截图并保存到文件 /var/mobile/1.png
--
screen.image(100, 100, 200, 200):save_to_album() -- 截取左上坐标为 100, 100 右下坐标为 200, 200 的区域图像保存到相册
--
pasteboard.write(screen.image(100, 100, 200, 200):png_data(), "public.png")
-- 截取左上坐标为 100, 100 右下坐标为 200, 200 的区域图像写入到剪贴板
```
**注**：上述代码中使用了非本章函数 [`:save_to_album`](/docs/handbook/image/imagem_save_to_album.md)、[`:save_to_png_file`](/docs/handbook/image/imagem_save_to_png_file.md)、[`:png_data`](/docs/handbook/image/imagem_png_data.md)、[`pasteboard.write`](/docs/handbook/pasteboard/pasteboard.write.md)

---

Source: [学习 Lua 应当注意的](https://xxtouch.app/docs/handbook/supplement/abc.md)
Path: handbook/supplement/abc.md

# 学习 Lua 应当注意的


- 数组下标从 1 开始（区别于 C 语言系的 0）。
- `string.len` 返回的是字符串的**字节数**，而非字符个数。
- 所有未初始化的变量均为 `nil`。对表中的值赋 `nil` 会将其从表中删除。
- 只有 `nil` 和 `false` 是逻辑假，其他所有值（包括 `0`）都是逻辑真。
- 字符串和数字在数学运算和比较时会自动转换，例如 `a = '1' + 2`。
- 字符串拼接使用 `..` 连接符，例如 `a = '1' .. 2`。
- 两个浮点数不能用 `==` 直接比较。错误用法示例：`if 89.7 == (3 * 29.9) then`。
- 可完全表示为整数的浮点数与对应整数相等（例如 `1.0 == 1`）。

---

Source: [获取设备当前可用内存值 (sys.available_memory)](https://xxtouch.app/docs/handbook/sys/sys.available_memory.md)
Path: handbook/sys/sys.available_memory.md

# 获取设备当前可用内存值 (sys.available_memory)


## 声明

```lua
可用内存 = sys.available_memory()
```


## 返回值

- 可用内存
    实数型，返回当前设备的空闲内存值（单位：MB）


## 示例

```lua
sys.alert('当前可用内存为：'..sys.available_memory()..'MB')
```

---

Source: [touch 示例代码](https://xxtouch.app/docs/handbook/touch/samples-1.md)
Path: handbook/touch/samples-1.md

# touch 示例代码


## 示例

```lua
-- 可以这样：
touch.on(306, 300):step_len(2):step_delay(0):move(350, 800):msleep(1000):off()
--
-- 上面那个例子也能写成这样：
touch.on(306, 300)  -- 模拟手指在 306,300 这个坐标点接触屏幕
    :step_len(2)   -- 设置移动步长为 2
    :step_delay(0) -- 设置移动每步延迟为 0
    :move(350, 800) -- 以上面两个参数所设置移动到 350,800 这个坐标
    :msleep(1000)   -- 等 1000 毫秒 (也就是 1 秒)
:off()             -- 手指离开屏幕
--
-- 或是这样：
local te = touch.on(306,300)
te:step_len(2)
te:step_delay(0)
te:move(350, 800)
te:msleep(1000)
te:off()
--
-- 通常情况下，滑动代码可以写成这样
touch.on(306, 300)
    :move(350, 800)
    :msleep(1000)
:off()
--
-- 等效于
touch.on(306, 300):move(350, 800):msleep(1000):off()
--
-- 也可以这样用于模拟轻触屏幕一次
touch.on(306, 300):msleep(30):off()
--
```


## 快速精确滑动技巧

```lua
-- 更稳定的快速精确滑动方式通常是：
-- 先快速滑到略微超过目标的位置，再往回滑到目标位置
touch.on(125, 2000) -- 在起始坐标按下
    :step_len(10)   -- 步长设长以便快速滑动
    :step_delay(1)  -- 步骤延迟设为 1ms 以便快速滑动
    :move(125, 505 - 20) -- 先快速滑到略微超过目标的位置（这里示例是向上滑，所以 y 更小）
    :step_len(1)    -- 往回滑时把步长缩短，减少惯性
    :step_delay(20) -- 往回滑时适当减速，让轨迹更稳
    :move(125, 505) -- 再往回滑到目标位置
    :delay(200)     -- 抬起前停顿一段时间
:off()              -- 抬起手指
```

- 上面的例子是“向上滑”的情况；如果是向下、向左、向右滑动，就把“超过目标的位置”换成对应方向上略微越过目标的位置。
- 不涉及屏幕边缘时，一般只要先滑到超过目标的位置，再往回滑到目标位置，就已经是精确且没有惯性的快速滑动。
- 如果“超过目标的位置”会落到屏幕外，那么这一步实际上是无效的，所以应该先快速滑到屏幕边缘，再往回滑一点，最后慢慢滑到目标位置。
- 就算目标位置刚好在屏幕边缘，也建议先滑到边缘、再往回滑一点、最后慢慢滑回目标位置，这样通常比直接停在边缘更稳定。

---

Source: [获取文本元素列表 (ui_element.list_text_elements)](https://xxtouch.app/docs/handbook/ui_element/ui_element.list_text_elements.md)
Path: handbook/ui_element/ui_element.list_text_elements.md

# 获取文本元素列表 (ui_element.list_text_elements)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
元素列表, 错误信息 = ui_element.list_text_elements([ 进程号或选项 ])
```

## 参数

- 进程号或选项
    可选参数，整数型或表型。整数型表示目标 App 进程号；表型可参考 [通用选项说明](options.md)。

**20261115 起**支持[属性排除选项](options.md#attribute-exclusions)。

## 返回值

- 元素列表
    表型，UI 元素数组。失败时为 `nil`。
- 错误信息
    文本型，失败原因。

## 说明

> 获取当前目标 App 的文本元素列表。
> 返回元素中的坐标字段单位为物理像素。
> 该接口为兼容旧脚本保留，默认查询策略较保守；新脚本需要定位元素时优先考虑 [`find`](ui_element.find.md) 或 [`snapshot`](ui_element.snapshot.md)。

## 示例

```lua
local ui_element = require("ui_element")

local list, err = ui_element.list_text_elements({
    max_level = 1,
    include_hit_state = true,
})

if list then
    for _, item in ipairs(list) do
        if item.text then
            nLog(item.text)
        end
    end
else
    sys.toast(err)
end
```

**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [生成下一个基于计数器的一次性验证码 (utils.hotp_next)](https://xxtouch.app/docs/handbook/utils/utils.hotp_next.md)
Path: handbook/utils/utils.hotp_next.md

# 生成下一个基于计数器的一次性验证码 (utils.hotp_next)


## 声明

```lua
验证码, 错误信息 = utils.hotp_next(链接[, 密钥])
```


## 参数

- 链接
    文本型，HOTP 链接，格式为 `otpauth://hotp/...`
- 密钥
    文本型，Base32 格式，可选参数；传入后将使用该密钥生成验证码


## 返回值

- 验证码
    文本型，生成的一次性验证码
- 错误信息
    文本型，生成失败时返回错误信息


## 说明

> **该函数在 20260107 以后版本方可使用**
> 根据 HOTP 链接生成下一个一次性验证码
> 如需自行指定计数器，请使用 [`utils.hotp_counter`](utils.hotp_counter.md)
> 链接中通常需要包含 `secret`，可选包含 `digits`、`algorithm`
> `algorithm` 可使用 `SHA1`、`SHA256` 或 `SHA512`


## 示例

```lua
local url = "otpauth://hotp/Demo:alice?secret=JBSWY3DPEHPK3PXP&issuer=Demo&digits=6&algorithm=SHA1"

local code, err = utils.hotp_next(url)
if code then
    nLog(code)
else
    nLog(err)
end
```

---

Source: [覆盖写入配置表到某个配置分区 (xui.write)](https://xxtouch.app/docs/handbook/xui/xui.write.md)
Path: handbook/xui/xui.write.md

# 覆盖写入配置表到某个配置分区 (xui.write)


## 声明

```lua
操作成败 = xui.write(配置分区, 配置)
```


## 参数

- 配置分区
    文本型，配置界面中的配置分区（defaults）标识符
- 配置
    表型，配置的键值对


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false


## 说明

> 该函数适合一次性批量写入多项配置；若当前正显示着配置界面，会立刻更新界面上的显示值
> 该函数不会过滤值类型；如需保证值类型合法，可于写入后使用 `xui.setup` 校验修正
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.setup('interface.xui')
local dict = xui.read('com.yourcompany.A-Script-Bundle')
dict['enabled'] = true
xui.write('com.yourcompany.A-Script-Bundle', dict)
xui.setup('interface.xui')
```

---

Source: [通过应用程序 bid 获取应用的图标数据 (app.png_data_for_bid)](https://xxtouch.app/docs/handbook/app/app.png_data_for_bid.md)
Path: handbook/app/app.png_data_for_bid.md

# 通过应用程序 bid 获取应用的图标数据 (app.png_data_for_bid)


## 声明

```lua
PNG图片数据 = app.png_data_for_bid(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- PNG 图片数据
    字符串型 或 nil，应用图标的 PNG 二进制数据，如果应用不存在则返回 nil


## 示例

```lua
-- 将微信的图标保存到相册
image.load_data(app.png_data_for_bid("com.tencent.xin")):save_to_album()
```
**注**：上述代码中使用了非本章函数 [`image.load_data`](/docs/handbook/image/image.load_data.md)、[`:save_to_album`](/docs/handbook/image/imagem_save_to_album.md)

---

Source: [获取设备类型 (device.type)](https://xxtouch.app/docs/handbook/device/device.type.md)
Path: handbook/device/device.type.md

# 获取设备类型 (device.type)


## 声明

```lua
设备类型 = device.type()
```


## 返回值

- 设备类型
    文本型，形如 `"iPhone3,1"`、`"iPad13,1"` 的机型标识字符串


## 说明

> 获取设备类型
> 该函数可在 XUI 中使用


## 示例

```lua
if device.type() == "iPhone3,1" then
    -- 是 iPhone 4
end
```

---

Source: [给对话框加上一个开关 (:add_switch)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_switch.md)
Path: handbook/dialog/dialogm_add_switch.md

# 给对话框加上一个开关 (:add_switch)


## 声明

```lua
对话框对象 = 对话框对象:add_switch(开关标签 [, 开关默认状态 ])
```


## 参数

- 开关标签
    文本型，开关左侧标签显示的文本
- 开关默认状态
    布尔型，可选参数，开关的初始状态，true 为开、false 为关，默认 false

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    布尔型，返回开关的最终状态


## 说明

> 给对话框加上一个开关


## 示例

```lua
local c, s = dialog():add_switch('一个开关', false):show()
sys.alert(s["一个开关"])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [移除文件中指定行 (file.remove_line)](https://xxtouch.app/docs/handbook/file/file.remove_line.md)
Path: handbook/file/file.remove_line.md

# 移除文件中指定行 (file.remove_line)


## 声明

```lua
操作成败, 被删除行的内容 = file.remove_line(文件路径, 行号)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行号
    整数型，指定行号，0 为最后一行 \+1，负数则为倒数行号

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 被删除行的内容
    字符串型，当操作成功的时候，返回被移除的行，失败返回错误信息


## 说明

> 移除文件中指定行，如果被移除的行之后还有行，那么后面行会往前移
> 该函数会自动剔除掉文件头部的 UTF8-BOM

## 示例

```lua
local success, line = file.remove_line("/var/mobile/1.txt", 3)
if success then
    sys.alert("操作成功，被删除的行的内容是："..line)
else
    sys.alert("操作失败："..line)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [输出图片对象到一个 JPEG 格式的文件 (:save_to_jpeg_file)](https://xxtouch.app/docs/handbook/image/imagem_save_to_jpeg_file.md)
Path: handbook/image/imagem_save_to_jpeg_file.md

# 输出图片对象到一个 JPEG 格式的文件 (:save_to_jpeg_file)


## 声明

```lua
图片:save_to_jpeg_file(文件路径 [, 图像质量 ])
```

## 参数

- 文件路径
    文本型，需要保存到图片文件的绝对路径
- 图像质量
    实数型，可选参数，图片质量，取值范围 0.0~1.0，默认 1.0


## 说明

> 输出图片对象到一个 JPEG 格式的文件，扩展名不限于 `.jpg`
> 关键词：有损压缩、图像压缩、图片质量


## 示例

```lua
-- 截全屏图片保存到文件
screen.image():save_to_jpeg_file("/var/mobile/1.jpg")
```
```lua
-- 截全屏图片保存到文件，JPEG 质量设为 0.4（较低质量以减小体积）
screen.image():save_to_jpeg_file("/var/mobile/1.jpg", 0.4)
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)

---

Source: [松开硬件键盘按键 (:up)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_up.md)
Path: handbook/key/hardware_keyboardm_up.md

# 松开硬件键盘按键 (:up)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = 硬件键盘对象:up(按键码)
是否成功, 错误信息 = 硬件键盘对象:up(Usage_Page, Usage_ID)
```

## 参数

- 按键码
    文本型，与 [`key.press`](/docs/handbook/key/key.press.md) 使用同一份按键名称映射。
- Usage Page
    整数型，当前硬件键盘对象只接受 Keyboard/Keypad Usage Page `0x07`。
- Usage ID
    整数型，物理按键编号，不是字符编码。

## 返回值

- 是否成功
    布尔型，发送成功时返回 `true`，失败时返回 `false`。
- 错误信息
    文本型，发送失败时返回错误信息。

## 说明

> 松开一个之前由 [`:down`](hardware_keyboardm_down.md) 按下的硬件键盘按键。

同一键盘正在执行 `:press` 或 `:send_text` 序列时，本方法返回 `false, "hardware keyboard is busy"`。发送失败时不会自动改用其它输入方式重试。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

assert(keyboard:down("LEFTSHIFT"))
assert(keyboard:up("LEFTSHIFT"))

assert(keyboard:disconnect())
```

---

Source: [从进程队列词典尾部弹出一个值 (proc_queue_pop_back)](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_back.md)
Path: handbook/proc/proc_queue_pop_back.md

# 从进程队列词典尾部弹出一个值 (proc_queue_pop_back)


## 声明

```lua
值 = proc_queue_pop_back(键)
```


## 参数

- 键
    字符串型


## 返回值

- 值
    字符串型，返回弹出的值，如果队列不存在或为空，则返回空字符串


## 说明

> **所有以 "xxtouch." 或 "1ferver." 开头的进程队列词典全部被保留**
> 从进程队列词典尾部弹出一个值
> 如果队列不存在或为空，则弹出一个空字符串


## 示例

```lua
local billno = proc_queue_pop_back("billnos")
if billno ~= "" then
    print(billno)
else
    print("no bill")
end
```

---

Source: [! 屏幕区域文字识别 (screen.ocr_text)](https://xxtouch.app/docs/handbook/screen/screen.ocr_text.md)
Path: handbook/screen/screen.ocr_text.md

# ! 屏幕区域文字识别 (screen.ocr_text)


## 声明

```lua
识别结果, 结果详情 = screen.ocr_text(左, 上, 右, 下 [, 引擎选项, 二值化选项 ])
```


## 参数

- 左, 上, 右, 下
    整数型，用于表示屏幕上的区域，传入 `0, 0, 0, 0` 代表全屏
- 引擎选项
    可选参数，表型，用于选择识别语言及识别引擎
    <details>

    <summary>参数结构</summary>

    ```lua
    {
        -- 如果将 engine 字段设为 "apple"，则使用 iOS 13 以上苹果自带的 Vision.framework 进行识别
        -- 你可以使用 image.vision_supported_recognition_languages() 函数获取 Vision.framework 支持的 OCR 模型列表
        -- 如果将 engine 字段设为 "paddle"，则使用 Paddle-Lite 引擎识别。可使用 lang 指定模型
        -- 例如 lang = "ppocr_ch" 则使用模型 /var/mobile/Media/1ferver/models/ppocr_ch
        -- Paddle-Lite 引擎支持 *.nb 格式的 Slim 模型
        engine = "apple" | "paddle" | "tesseract",
        lang = "zh-Hans",
    }
    ```
    </details>

    <details>

    <summary>各版本 iOS 内置的 Vision.framework 支持的 OCR 模型列表</summary>

    ```lua
    { -- iOS 13
        [1] = "en-US",
    }

    { -- iOS 14~15
        [1] = "en-US",
        [2] = "fr-FR",
        [3] = "it-IT",
        [4] = "de-DE",
        [5] = "es-ES",
        [6] = "pt-BR",
        [7] = "zh-Hans",
        [8] = "zh-Hant",
    }

    { -- iOS 16
        [ 1] = "en-US",
        [ 2] = "fr-FR",
        [ 3] = "it-IT",
        [ 4] = "de-DE",
        [ 5] = "es-ES",
        [ 6] = "pt-BR",
        [ 7] = "zh-Hans",
        [ 8] = "zh-Hant",
        [ 9] = "yue-Hans",
        [10] = "yue-Hant",
        [11] = "ko-KR",
        [12] = "ja-JP",
        [13] = "ru-RU",
        [14] = "uk-UA",
    }
    ```
    </details>
- 二值化选项
    实数型，二值化阈值，可参考 [图片自动二值化](/docs/handbook/image/imagem_cv_binaryzation.md)
    表型，自定义二值化色偏，参考 [图片手动二值化](/docs/handbook/image/imagem_binaryzation.md)
    文本型，自定义二值化色偏，参考 [图片手动二值化](/docs/handbook/image/imagem_binaryzation.md)

## 返回值

- 识别结果
    文本型，识别返回的文字
- 结果详情
    表型
    <details>

    <summary>OCR 识别的结果详情结构</summary>

    ```lua
    {
        {
            ["y"] = number_value,
            ["x"] = number_value,
            ["w"] = number_value,
            ["h"] = number_value,
            ["confidence"] = number_value(0.0000 ~ 1.0000),
            ["text"] = string_value,
        },
        ...
    }
    ```
    </details>


## 说明

> 当前函数坐标值参数及返回值均受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> 为保证向前兼容，不指定识别引擎时，默认使用过时的 tesseract 引擎进行文字识别
> **软件版本在 1.3.8 以上方支持 Apple 和 PaddleLite 识别引擎**
> [PaddleLite 简体中文普通版模型（需要解压缩）](https://xxtouch.lanzout.com/iL57a38ww71e)
> [PaddleLite 简体中文完全版模型（需要解压缩）](https://xxtouch.lanzout.com/iiQYx38ww6fc)
> [PaddleLite 繁体中文识别模型（需要解压缩）](https://xxtouch.lanzout.com/iNNpU38wyb3c)
> [PaddleLite 英文数字识别模型（需要解压缩）](https://xxtouch.lanzout.com/iiKtE3994q8f)
> [PaddleLite 日文识别模型（需要解压缩）](https://xxtouch.lanzout.com/iYXfK3boux0h)
> [PaddleLite 韩文识别模型（需要解压缩）](https://xxtouch.lanzout.com/ieCCH3bouxda)
> 也可从 [PaddleOCR 模型列表](https://gitee.com/paddlepaddle/PaddleOCR/blob/release/2.4/doc/doc_ch/models_list.md) 下载对应模型转换成 `det_opt.nb`、`cls_opt.nb`、`rec_opt.nb`, 然后找到对应的 [`dict.txt`](https://gitee.com/paddlepaddle/PaddleOCR/tree/release/2.4/ppocr/utils/dict) 配套使用

## 示例

```lua
-- 1.3.8 以上示例
txt, info = screen.ocr_text(187, 882, 298, 914, "en-US")   -- iOS 13 以上可使用苹果内置的 en-US 模型识别英文数字
sys.toast("识别结果："..txt:atrim())

txt, info = screen.ocr_text(187, 882, 298, 914, "zh-Hans") -- iOS 14 以上可使用苹果内置的 zh-Hans 模型识别简体中文
sys.toast("识别结果："..txt:atrim())

txt, info = screen.ocr_text(187, 882, 298, 914, {
    engine = "apple", -- 使用 Apple 引擎
    lang = "zh-Hans"  -- 使用简体中文识别模型
}, "9D5D39-0F1F26,D3D3D2-2C2C2D")
sys.toast("识别结果："..txt:atrim())

txt, info = screen.ocr_text(0, 0, 0, 0, {
    engine = "paddle", -- 使用 PaddleLite OCR 引擎
    lang = "ppocr_ch", -- 使用 ppocr_ch 模型
})
sys.toast("识别结果："..txt:atrim())
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`string.atrim`](/docs/handbook/ext-string/string.atrim.md)


## 旧版遗留（不推荐）
> 内置的 tesseract 已经不再推荐使用，只是为了保证对旧脚本的兼容性，它在当前版本的 XXTouch 中依然是默认 OCR 引擎
> 内置默认 OCR 引擎为 tesseract 3\.02 版，版本不对或者字库文件损坏会导致 XXTouch 脚本服务崩溃
> XXTouch 已内置 eng 识别库 \[A\-Za\-z0\-9\] 能识别常规英文和数字
> 如果需要做简体中文或是其它语言文字识别
> 需要手动导入相关的字库文件到设备的 `/var/mobile/Media/1ferver/tessdata/` 目录
> 这里提供 [简体中文字库（需要解压缩）](https://xxtouch.lanzout.com/iAxmN328t23i)


## 旧版遗留示例（不推荐）

```lua
-- 示例 1：
local txt = screen.ocr_text(187, 882, 298, 914) -- 默认配置是使用 tesseract 引擎英文数字模式识别文字
sys.toast("识别结果："..txt:atrim())
--
-- 示例 2：
local txt = screen.ocr_text(465, 241, 505, 269, "eng", "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
sys.toast("识别结果："..txt:atrim())
--
-- 示例 3：
local txt = screen.ocr_text(465, 241, 505, 269, "eng", { {0x9D5D39, 0x0F1F26}, {0xD3D3D2, 0x2C2C2D} }) -- 使用色偏二值化识别，同上
sys.toast("识别结果："..txt:atrim())
--
-- 示例 4：
local txt = screen.ocr_text(187, 882, 298, 914, {
  lang = "chi_sim",         -- 使用 tesseract 引擎简体中文库识别（注意，简体中文库不是内置的）
  white_list = "你我他",      -- 白名单设为 "你我他"
})
sys.toast("识别结果："..txt:atrim())
--
-- 示例 5：
local txt = screen.ocr_text(187, 882, 298, 914, {
  lang = "eng",
  white_list = "1234567890",      -- 自定义使用白名单限制仅识别为数字
}, "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
sys.toast("识别结果："..txt:atrim())
```

---

Source: [开发常见运行期错误参考](https://xxtouch.app/docs/handbook/supplement/runtime-errors.md)
Path: handbook/supplement/runtime-errors.md

# 开发常见运行期错误参考


|错误描述片段|原因|处理方式|
|------|----|----|
|attempt to perform arithmetic on a|尝试对非数值进行了数学运算 (\+、-、\*、/) |数学运算之前，检查运算输入是否都为数字|
|attempt to compare|尝试对非法值进行了比较运算 (\>、\<、\>=、\<=) |比较运算之前，检查运算输入是否双方可以进行比较运算|
|attempt to concatenate a|尝试对非字符串值进行了连接 (..) |在进行字符串连接之前，先确定连接双方都为字符串|
|attempt to call a|尝试调用了一个不是函数的变量|调用一个函数之前，先确定其是否为一个函数|
|attempt to index a|尝试对一个非表变量进行索引 (下标运算) |在从数组变量或关联数组变量中取值前，先确定其是否为一个表|
|attempt to yield across a C-call boundary|尝试在不能让出的调用块中让出|[require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 一个模块的时候，请确认被 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 的模块返回之前没有调用会让出的函数 (手册上函数前带叹号) 。还有就是不要尝试在带 C 回调的函数中使用会让出的函数 (手册上函数前带叹号) 。|
|invalid order function for sorting|非法的排序函数，通常发生在排序函数的规则逻辑不够明确的情况下|调用排序函数时，明确排序规则，不要出现 a 大于 b 成立同时小于 b 也成立的规则|
|bad argument \#1 to 'xxx' \(number expected, got nil\)|调用 xxx 函数时，第 \#1 个参数的类型不正确，需要 number 却传入了 nil|参数错误，请传入合适的参数|
|bad argument \#2 to 'xxx' \(number has no integer representation\)|调用 xxx 函数时，第 \#2 个参数无法转换成整数|参数错误，请传入合适的参数|
|bad argument \#3 to 'xxx'|调用 xxx 函数时，第 \#3 个参数非法|参数错误，请传入合适的参数|


- 使用 [require](https://cloudwu.github.io/lua53doc/manual.html#pdf-require) 的时候抛出 attempt to yield across a C-call boundary 错误的权宜解决方案
    + 1、在被 require 的模块代码前加上一行 `return function()`
    + 2、在被 require 的模块代码最后加上一行 `end`
    + 3、require 的时候，后面多加一对括号，例如 `require('A')` 改成 `require('A')()`

---

Source: [获取设备当前未使用的存储空间值 (sys.free_disk_space)](https://xxtouch.app/docs/handbook/sys/sys.free_disk_space.md)
Path: handbook/sys/sys.free_disk_space.md

# 获取设备当前未使用的存储空间值 (sys.free_disk_space)


## 声明

```lua
剩余空间 = sys.free_disk_space([挂载点])
```

## 参数

- 挂载点
    文本型，默认有效取值范围为 `"/var"` 或是 `"/"`，分别代表用户空间和系统空间。有外部存储比如内存卡的时候可以有其它值

## 返回值

- 剩余空间
    实数型，返回设备当前未使用的存储空间值 \(单位：MB\)


## 示例

```lua
sys.alert(
    '当前系统空间剩余\n'..sys.free_disk_space('/')..'MB\n\n'..
    '当前用户空间剩余\n'..sys.free_disk_space('/var')..'MB'
)
```

---

Source: [获取坐标处的 UI 元素 (ui_element.text_element_at_position)](https://xxtouch.app/docs/handbook/ui_element/ui_element.text_element_at_position.md)
Path: handbook/ui_element/ui_element.text_element_at_position.md

# 获取坐标处的 UI 元素 (ui_element.text_element_at_position)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
元素, 错误信息 = ui_element.text_element_at_position(横坐标, 纵坐标 [, 进程号或选项 ])
```

## 参数

- 横坐标, 纵坐标
    整数型，屏幕坐标，单位为物理像素。
- 进程号或选项
    可选参数，整数型或表型。整数型表示目标 App 进程号；表型可参考 [通用选项说明](options.md)。

## 返回值

- 元素
    表型，坐标处命中的 UI 元素。失败时为 `nil`。
- 错误信息
    文本型，失败原因。

## 说明

> 该接口适合在已经知道坐标点时反查 UI 元素，例如根据图像识别或 OCR 结果理解附近控件。
> 它不是坐标点击接口；固定坐标点击请使用 [touch.tap](/docs/handbook/touch/touch.tap.md)。
> 坐标处为空白或目标界面没有提供可读元素时可能失败。

## 示例

```lua
local ui_element = require("ui_element")

local item, err = ui_element.text_element_at_position(300, 500, {
    include_hit_state = true,
    max_level = 1,
})

if item then
    nLog(item.text or item.value or "")
else
    sys.toast(err)
end
```

**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)、[`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [时间戳转换为 RFC 1123 格式文本 (utils.date_to_rfc1123)](https://xxtouch.app/docs/handbook/utils/utils.date_to_rfc1123.md)
Path: handbook/utils/utils.date_to_rfc1123.md

# 时间戳转换为 RFC 1123 格式文本 (utils.date_to_rfc1123)


## 声明

```lua
rfc1123 = utils.date_to_rfc1123(timestamp)
```


## 参数

- timestamp
    数值型，时间戳


## 返回值

- rfc1123
    文本型，RFC 1123 格式的时间文本


## 说明

> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
nLog(utils.date_to_rfc1123(1749490800)) -- 输出：Mon, 09 Jun 2025 17:40:00 GMT
nLog(utils.date_to_rfc1123(os.time())) -- 输出类似：Mon, 09 Jun 2025 17:40:00 GMT
```

---

Source: [清除某个配置分区所有的配置 (xui.clear)](https://xxtouch.app/docs/handbook/xui/xui.clear.md)
Path: handbook/xui/xui.clear.md

# 清除某个配置分区所有的配置 (xui.clear)


## 声明

```lua
操作成败 = xui.clear(配置分区)
```


## 参数

- 配置分区
    文本型，配置界面中的配置分区（defaults）标识符


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false，操作失败通常是因为指定配置不存在


## 说明

> 该函数用于一次性清除指定配置分区下的所有已存储配置；若当前正显示着配置界面，会立刻更新界面上的显示值
> 可于清除后使用 `xui.setup` 再次生成配置界面的默认配置
> 脚本配置界面标准参考 [XUI](/XUI/README.md)


## 示例

```lua
xui.clear('com.yourcompany.A-Script-Bundle')
xui.setup('interface.xui')
```

---

Source: [通过应用程序 bid 获取其 pid (app.pid_for_bid)](https://xxtouch.app/docs/handbook/app/app.pid_for_bid.md)
Path: handbook/app/app.pid_for_bid.md

# 通过应用程序 bid 获取其 pid (app.pid_for_bid)


## 声明

```lua
进程号 = app.pid_for_bid(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 进程号
    整数型，如果应用程序正在运行，则返回其 pid，否则返回 0


## 示例

```lua
local qqpid = app.pid_for_bid("com.tencent.mqq")
if qqpid~=0 then
    sys.alert("当前QQ正在运行，进程号是："..qqpid)
else
    sys.alert("当前QQ没有在运行")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [文本分词器模块](https://xxtouch.app/docs/handbook/coreml/coreml.tokenizer_module.md)
Path: handbook/coreml/coreml.tokenizer_module.md

# 文本分词器模块

文本分词器模块负责把字符串转换成模型可用的 token ID 序列。
这层只做分词、编码与反向解码，不负责模型推理。典型流程是先把文本编码成 `MLMultiArray` 或 `onnxruntime.tensor`，再把编码结果传给对应的 CoreML 或 ONNX Runtime 推理器。

当前这套模块的目标是“端侧推理够用”：

- `WordPiece` 兼容度最高，适合 `BERT`、`CN-CLIP` 一类模型
- `BPE` 和 `SentencePiece` 采用轻量兼容策略，适合多数端侧编码场景
- 不把复杂分词器训练、采样或完整上游生态行为搬到运行时里

> **该模块在 20260319 以后版本方可使用**

## 创建分词器

### `coreml.new_text_tokenizer(opts)`

```lua
文本分词器对象, 错误信息 = coreml.new_text_tokenizer({
    type = 分词器类型,
    vocab_path = 词表路径,
    merges_path = merges 文件路径,
    model_path = SentencePiece 模型路径,
    pattern = 正则表达式,
    context_length = 上下文长度,
    do_lower_case = 是否转小写,
    vocab_limit = 词表上限,
    clean_text = 是否先清洗文本,
    add_bos = 是否添加起始 token,
    add_eos = 是否添加结束 token,
    bos_token = 起始 token 文本,
    eos_token = 结束 token 文本,
    pad_token = 填充 token 文本,
    unk_token = 未知 token 文本,
})
```

### `type` 取值

- `wordpiece` / `bert` / `cn_clip`
- `bpe` / `gpt2_bpe` / `clip_bpe`
- `sentencepiece` / `spm`
- `regex` / `pattern`
- `byte` / `bytes`
- `whitespace` / `space`
- `character` / `char`

默认 `wordpiece`。

如果 `coreml.new_text_tokenizer(...)` 的第一个参数不是 table，会直接按 `wordpiece` 快捷构造处理，也就是等价于 `coreml.new_wordpiece_tokenizer(vocab_path)` 这类用法。

### 常用参数

- `vocab_path`
  文本型，词表文件路径。

- `merges_path`
  文本型，`BPE` 系分词器使用的 merges 文件路径。

- `model_path`
  文本型，`SentencePiece` 兼容模式可使用的 `.model` 文件路径。

- `pattern`
  文本型，`Regex` 分词器使用的正则表达式。

- `context_length`
  整数型，可选参数，输出 token 序列长度。

- `do_lower_case`
  布尔型，可选参数，是否先转小写。

- `vocab_limit`
  整数型，可选参数，仅 `WordPiece` 常用，用于限制词表上限。

- `clean_text`
  布尔型，可选参数，是否在分词前先做基础文本清洗。

- `add_bos / add_eos`
  布尔型，可选参数，是否在编码结果前后附加起始 / 结束 token。

- `bos_token / eos_token / pad_token / unk_token`
  文本型，可选参数，对应特殊 token 在词表中的文本。

不是所有分词器类型都支持上面所有字段。当前实现的必填项与默认值如下：

- `wordpiece`
  支持直接传 `vocab_path` 字符串，或传 table；要求 `vocab_path` 存在；默认 `context_length = 52`、`do_lower_case = true`、`vocab_limit = 21128`，并要求词表里存在 `[PAD]`、`[UNK]`、`[CLS]`、`[SEP]`
- `bpe`
  只接受 table；要求 `vocab_path` 和 `merges_path`；默认 `context_length = 77`、`do_lower_case = false`、`clean_text = false`、`add_bos = false`、`add_eos = false`
- `sentencepiece`
  只接受 table；要求 `vocab_path` 或 `model_path` 至少一个；默认 `context_length = 77`、`do_lower_case = false`、`clean_text = true`、`bos_token = "<s>"`、`eos_token = "</s>"`、`pad_token = "<pad>"`、`unk_token = "<unk>"`
- `regex`
  只接受 table；要求 `vocab_path` 和 `pattern`；默认 `context_length = 77`、`do_lower_case = false`、`clean_text = true`
- `whitespace` / `character` / `byte`
  只接受 table；要求 `vocab_path`；默认 `context_length = 77`、`do_lower_case = false`、`clean_text = true`

选择建议：

- 已知模型使用 `vocab.txt + WordPiece`，就选 `wordpiece`
- 已知模型使用 `vocab.json + merges.txt`，就选 `bpe`
- 已知模型使用 `.vocab` 或 `.model`，就选 `sentencepiece`
- 只有简单规则切词需求时，再考虑 `regex`、`whitespace`、`character`、`byte`

### 返回值

- 文本分词器对象
  对象型，创建失败返回 `nil`。

- 错误信息
  文本型，成功时为 `nil`，失败时返回错误信息。

### 说明

- 分词器对象适合创建一次后复用，不建议每次编码都重新构造
- 创建阶段主要决定三件事：分词算法、词表来源、固定输出长度
- 如果模型效果明显不对，优先检查分词器类型、词表文件、special token 配置和 `context_length` 是否与训练时一致
- `WordPiece` 是当前最完整、最稳的一类
- `BPE` 和 `SentencePiece` 以端侧编码兼容为目标，不承诺复刻所有上游实现的全部细节

## 快捷构造器

以下快捷函数本质上都是对 `coreml.new_text_tokenizer(...)` 的转发，适合在你已经确定分词器类型时直接使用。

### `coreml.new_wordpiece_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "wordpiece", ... })`
- 适合 `BERT`、`CN-CLIP` 等 `WordPiece` 风格文本模型
- 也支持直接传词表路径字符串：`coreml.new_wordpiece_tokenizer(vocab_path)`

### `coreml.new_bpe_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "bpe", ... })`
- 同时覆盖 `gpt2_bpe`、`clip_bpe` 一类 `vocab.json + merges.txt` 模型

### `coreml.new_sentencepiece_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "sentencepiece", ... })`
- 使用面向端侧推理的轻量兼容实现
- 支持 `.vocab` 和 `.model`

### `coreml.new_regex_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "regex", ... })`
- 适合基于规则切词和简单词表映射的场景

### `coreml.new_byte_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "byte", ... })`
- 会先把文本转成 `UTF-8` 字节流，再按字节查词表

### `coreml.new_whitespace_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "whitespace", ... })`
- 适合空格切词、词表直查的轻量文本模型

### `coreml.new_character_tokenizer(opts)`

- 等价于 `coreml.new_text_tokenizer({ type = "character", ... })`
- 适合字符级文本模型

## 类型判断

### `coreml.is_text_tokenizer(value)`

```lua
是否文本分词器 = coreml.is_text_tokenizer(需要判断的值)
```

用于判断一个值是否为 `coreml_text_tokenizer_object`。

## 对象方法

### `:encode(text[, opts])`

```lua
编码结果, 错误信息 = 文本分词器对象:encode(文本)
```

或

```lua
编码结果, 错误信息 = 文本分词器对象:encode(文本, {
    output = "table" 或 "MLMultiArray" 或 "ort_tensor",
    data_type = 数据类型,
    pair_text = 配对文本,
    max_length = 最大长度,
    padding = 填充策略,
    truncation = 截断策略,
    return_attention_mask = 是否返回 attention mask,
    return_token_type_ids = 是否返回 token type ids,
    return_special_tokens_mask = 是否返回 special tokens mask,
})
```

把单个文本编码成 token 序列。

### `:encode_batch(texts[, opts])`

```lua
编码结果, 错误信息 = 文本分词器对象:encode_batch(文本数组)
```

或

```lua
编码结果, 错误信息 = 文本分词器对象:encode_batch(文本数组, {
    output = "table" 或 "MLMultiArray" 或 "ort_tensor",
    data_type = 数据类型,
    pair_text = 配对文本或配对文本数组,
    max_length = 最大长度,
    padding = 填充策略,
    truncation = 截断策略,
    return_attention_mask = 是否返回 attention mask,
    return_token_type_ids = 是否返回 token type ids,
    return_special_tokens_mask = 是否返回 special tokens mask,
})
```

一次编码多个文本，返回 batch 形式的 token 序列。

### `:decode(ids)`

```lua
文本, 错误信息 = 文本分词器对象:decode(ids)
```

把**单条** token id 序列反向解码成文本。

- `ids` 可以是 Lua 数组、`MLMultiArray`，或者 ORT tensor 之类的 tensor-like userdata
- `ids` 也可以是任何实现了 `shape()` 与 `to_table()` 的 tensor-like userdata
- 如果传入的是 batch 数据，会报错并提示改用 `decode_batch()`

### `:decode_batch(batch_ids)`

```lua
文本数组, 错误信息 = 文本分词器对象:decode_batch(batch_ids)
```

把 batch token id 序列反向解码成文本数组。

- `batch_ids` 可以是嵌套 Lua 数组、`MLMultiArray`，或者 ORT tensor 之类的 tensor-like userdata
- `batch_ids` 也可以是任何实现了 `shape()` 与 `to_table()` 的 tensor-like userdata

### `:vocab_size()`

```lua
词表大小 = 文本分词器对象:vocab_size()
```

返回当前分词器可用词表大小。

### `:context_length()`

```lua
上下文长度 = 文本分词器对象:context_length()
```

返回当前分词器的固定输出长度，也就是单次编码会补齐或截断到的长度。

## 编码与返回说明

- `output` 默认是 `"MLMultiArray"`，适合直接喂给 CoreML 模型
- `output = "table"` 适合调试、查看 token id，或兼容旧脚本
- `output = "ort_tensor"` 适合直接喂给 ONNX Runtime 文本模型
- `output = "ort_tensor"` 前必须先执行 `require("onnxruntime")`，这样 ORT 桥接接口才会被注入
- `output = "ort_tensor"` 依赖 ONNX Runtime，因此仅支持 **iOS 13+**
- 为兼容旧脚本，字段 `multi_array_output` 仍会被读取；但新代码建议统一使用 `output`

### `data_type` 规则

- `output = "MLMultiArray"` 时，`data_type` 可选 `"int32"`、`"float32"`、`"float16"`、`"double"`；`"float64"` 可作为 `"double"` 的别名
- `output = "MLMultiArray"` 时，默认 `data_type = "int32"`
- `output = "ort_tensor"` 时，`data_type` 可选 `"float16"`、`"float32"`、`"uint8"`、`"int8"`、`"int32"`、`"int64"`、`"double"`、`"bool"`
- `output = "ort_tensor"` 时，默认 `data_type = "int64"`

### `padding` / `truncation`

- `padding` 可以是布尔值，也可以是字符串
  - `true` 会映射到 `"max_length"`
  - `false` 会映射到 `"do_not_pad"`
- `truncation` 可以是布尔值，也可以是字符串
  - `true` 会映射到 `"longest_first"`
  - `false` 会映射到 `"do_not_truncate"`

### `pair_text`

- `encode()` 里可以传单个 `pair_text`
- `encode_batch()` 里可以传单个 `pair_text`，也可以传与 batch 大小一致的字符串数组

### 结构化返回

当以下任一字段为 `true` 时，`encode()` / `encode_batch()` 会返回结构化结果表，而不只是裸 token 序列：

- `return_attention_mask`
- `return_token_type_ids`
- `return_special_tokens_mask`

结构化结果常见字段：

- `input_ids`
- `length`
- `attention_mask`
- `token_type_ids`
- `special_tokens_mask`

对 batch 编码来说：

- `output = "table"` 时，保留每条样本自己的长度
- `output = "MLMultiArray"` / `"ort_tensor"` 时，会把 batch 补齐成规则矩阵后再返回

## 示例

```lua
local tokenizer = assert(coreml.new_text_tokenizer({
    type = "wordpiece",
    vocab_path = XXT_HOME_PATH.."/models/demo/vocab.txt",
    context_length = 52,
}))

local ids = assert(tokenizer:encode("星星", {
    output = "MLMultiArray",
    data_type = "int32",
}))

local structured = assert(tokenizer:encode("星星", {
    output = "table",
    return_attention_mask = true,
    return_token_type_ids = true,
}))

local ort = require("onnxruntime")

local input_ids = assert(tokenizer:encode("星星", {
    output = "ort_tensor",
    data_type = "int64",
}))

local batch = assert(tokenizer:encode_batch({
    "星星",
    "月亮",
}, {
    output = "ort_tensor",
}))

print(tokenizer:decode(structured.input_ids))
print(tokenizer:vocab_size())
print(tokenizer:context_length())
```

---

Source: [获取设备名 (device.name)](https://xxtouch.app/docs/handbook/device/device.name.md)
Path: handbook/device/device.name.md

# 获取设备名 (device.name)


## 声明

```lua
设备名 = device.name()
```


## 返回值

- 设备名
    文本型，返回用户给设备取的名字


## 说明

> 该函数可在 XUI 中使用


## 示例

```lua
sys.alert("设备的名字是："..device.name())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [给对话框加上一个选择器 (:add_picker)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_picker.md)
Path: handbook/dialog/dialogm_add_picker.md

# 给对话框加上一个选择器 (:add_picker)


## 声明

```lua
对话框对象 = 对话框对象:add_picker(选择器标签, 选项列表 [, 默认选中项 ])
```

## 参数

- 选择器标签
    文本型，选择器左侧标签显示的文本
- 选项列表
    表型，选择器的选项名顺序列表，选项名不允许重复
- 默认选中项
    文本型，可选参数，默认选中的选项名，默认为选项列表的第一项

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    文本型，返回被选中的选项名


## 说明

> 给对话框加上一个选择器


## 示例

```lua
local c, s = dialog():add_picker('一个选择器', {'选择1', '选择2', '选择3'}):show()
sys.alert('你的选择是：'..s['一个选择器'])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [获取一个文本文件的所有行 (file.get_lines)](https://xxtouch.app/docs/handbook/file/file.get_lines.md)
Path: handbook/file/file.get_lines.md

# 获取一个文本文件的所有行 (file.get_lines)


## 声明

```lua
行数组, 错误信息 = file.get_lines(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- 行数组
    顺序表型 或 nil，返回一个顺序表，文件不存在返回 nil
- 错误信息
    文本型，读取失败时的错误信息


## 说明

> 获取一个文本文件的所有行，空文件返回 0 行
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local lines = file.get_lines("/var/mobile/1.txt")
if lines then
    if #lines > 0 then
        sys.alert("文件第一行的内容是 "..lines[1])
    else
        sys.alert("文件是空的")
    end
else
    sys.alert("操作失败")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`string.strip_utf8_bom`](/docs/handbook/ext-string/string.strip_utf8_bom.md)

---

Source: [获取图片对象的 PNG 格式数据 (:png_data)](https://xxtouch.app/docs/handbook/image/imagem_png_data.md)
Path: handbook/image/imagem_png_data.md

# 获取图片对象的 PNG 格式数据 (:png_data)


## 声明

```lua
图片PNG数据 = 图片:png_data()
```


## 返回值

- 图片 PNG 数据
    字符串型，返回 PNG 数据，对这份数据的修改不会影响图片对象


## 说明

> 获取图片对象的 PNG 格式数据
> 性能上，该函数操作过程产生两次数据拷贝


## 示例

```lua
file.writes('/var/mobile/1.png', screen.image():png_data())
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)、[`file.writes`](/docs/handbook/file/file.writes.md)

---

Source: [! 按一下硬件键盘按键 (:press)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_press.md)
Path: handbook/key/hardware_keyboardm_press.md

# ! 按一下硬件键盘按键 (:press)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = 硬件键盘对象:press(按键码[, 按下时间])
是否成功, 错误信息 = 硬件键盘对象:press(Usage_Page, Usage_ID[, 按下时间])
```

## 参数

- 按键码
    文本型，与 [`key.press`](/docs/handbook/key/key.press.md) 使用同一份按键名称映射。
- Usage Page
    整数型，当前硬件键盘对象只接受 Keyboard/Keypad Usage Page `0x07`。
- Usage ID
    整数型，物理按键编号，不是字符编码。
- 按下时间
    实数型，可选参数，按下按键后保持的毫秒数，默认 10 毫秒。

## 返回值

- 是否成功
    布尔型，按下并释放成功时返回 `true`，失败时返回 `false`。
- 错误信息
    文本型，操作失败时返回错误信息。

## 说明

> 按下目标按键，等待指定时间后再将其松开。等待期间会隐式让出，在方法返回之前，其他[线程](/docs/handbook/thread/index.md)可能获得执行机会。

- 本方法会保护调用前已经按下的普通键和修饰键，不会为了完成当前操作而释放它们。
- 同一硬件键盘正在执行 `:press` 或 `:send_text` 序列时，新的操作返回 `false, "hardware keyboard is busy"`。
- 发送失败时不会自动改用其它输入方式重试。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

assert(keyboard:press("a"))
assert(keyboard:press(0x07, 4, 30)) -- Keyboard A，保持 30 毫秒

assert(keyboard:disconnect())
```

---

Source: [从进程队列词典弹出所有特定值 (proc_queue_pop_value)](https://xxtouch.app/docs/handbook/proc/proc_queue_pop_value.md)
Path: handbook/proc/proc_queue_pop_value.md

# 从进程队列词典弹出所有特定值 (proc_queue_pop_value)

## 声明

```lua
弹出指定值的个数 = proc_queue_pop_value(键, 指定值)
```


## 参数

- 键
    字符串型
- 指定值
    字符串型，将要被弹出的值

## 返回值

- 弹出指定值的个数
    整数型，返回被弹出的指定值的个数


## 说明

> **该函数在 20250106 以后的版本方可使用**
> **所有以 "xxtouch\." 或 "1ferver\." 开头的进程队列词典全部被保留**
> 从进程队列词典弹出所有特定值，返回被弹出的特定值的个数


## 示例

```lua
local count = proc_queue_pop_value("billnos", "name")
if count ~= 0 then
    print(count)
else
    print("no bill")
end
```

---

Source: [屏幕找图 (screen.find_image)](https://xxtouch.app/docs/handbook/screen/screen.find_image.md)
Path: handbook/screen/screen.find_image.md

# 屏幕找图 (screen.find_image)


## 声明

```lua
横坐标, 纵坐标 = screen.find_image(图片 [, 可信度, 左, 上, 右, 下 ])
查找结果 = screen.find_image(图片 [, 选项, 左, 上, 右, 下 ])
```

## 参数

- 图片
    字符串型，需要找的图片，可以是 png 或是 jpeg 格式的图片数据
    图片对象，或是一个图片对象 (可参考 [图片对象模块 (image)](/docs/handbook/image/index.md))
    文本型，需要找的图片文件路径，如果不是合法路径则会以数据方式解析
- 可信度
    整数型，可选参数，默认是数字 95，它表示找到的位置的可信度不小于 95 才会返回。可信度取值范围 0 ~ 100
- 选项
    表型，可选参数
    <details>

    <summary>参数结构</summary>

    ```lua
    {
        find_all = false | true, -- 可选参数，当该参数为 true 时，表示找到所有匹配项，返回值为一个表。默认为 false
        confidence_threshold = number_value(0.0 ~ 100.0), -- 可选参数，可信度超过该值的结果视为有效。默认 95
        downscale = number_value(0.1 ~ 1.0), -- 可选参数，值越小速度越快精度越低。默认 1.0 精度优先
        mask = image_object, -- 可选参数，标注需要查找的图片都有效区域，是一张与 img 尺寸相同的二值化图片，白色为有效区域，黑色为无效区域。默认 img 所有区域都有效
    }
    ```
    </details>
- 左, 上, 右, 下
    整数型，可选参数，搜索区域，默认 全屏


## 返回值

- 横坐标, 纵坐标
    整数型，当 `选项.find_all` 不为 true 时，仅返回符合要求的最可信的结果坐标。未找到任何可信度满足的坐标时返回 -1, -1
- 查找结果
    表型
    <details>

    <summary>当 选项.find_all 为 true 时，返回可信度不小于 选项.confidence_threshold 的多个值</summary>

    ```lua
    {
        {
            x = integer_value,
            y = integer_value,
            confidence = number_value(0.0 ~ 100.0),
        },
        ...
    }
    ```
    </details>


## 说明

> 在屏幕上寻找一个图像的位置，该函数会引用 image.cv 模块
> 当前函数坐标值参数及返回值均受 [`screen.init`](/docs/handbook/screen/screen.init.md) 函数初始化的坐标系影响
> **注意：** 若需要做多分辨率兼容，建议在分辨率最小的设备上截图；大分辨率截图无法在小分辨率设备上匹配到

### 1.3.8 以上版本中增强

- 允许使用 find_all 模式找到图像中所有超过可信度阈值的匹配项
- 允许使用 downscale 字段设置将图像精度降低查找以提升找图速度
- 允许使用 mask 标注图片中的有效区域以实现查找不规则形状图像


## 示例

[XXT 取色器 Windows 版.zip](https://github.com/havonz/XXTouchDebs/raw/refs/heads/master/%E7%9B%B8%E5%85%B3%E8%B5%84%E6%BA%90/XXT%20%E5%8F%96%E8%89%B2%E5%99%A8%201.0.36%20For%20Windows.7z)
```lua
-- 示例 1 (使用 XXT 取色器 Shift + 鼠标左键框选图像上的区域 可直接生成这样的代码) ：
x, y = screen.find_image( -- 原图位置 左上: 354, 274 | 右下: 358, 284
"\x89\x50\x4e\x47\x0d\x0a\x1a\x0a\x00\x00\x00\x0d\x49\x48\x44\x52\x00\x00\x00\x04\x00\x00\x00\x0a\x08\x02\x00\x00\x00\x1c\x99\x68\x59\x00\x00\x00\x61\x49\x44\x41\x54\x78\xda\x63\x78\xfd\xf4\xda\xff\xff\xff\xff\xfd\xfb\xf7\xed\xcb\x5b\x86\xf7\xaf\x1f\xfc\x87\x01\x86\x2f\x1f\x5f\x02\xa9\xef\xa7\xce\x7c\xdd\xb1\x9b\xe1\xe7\xf7\xcf\x40\xce\xeb\xb2\xea\x7b\xb2\x6a\x0c\x7f\xff\xfe\x01\x72\x9e\x78\x06\x82\x38\x20\xdd\xbf\x7e\xdd\x57\xd4\x82\x72\x7e\xdd\xba\x0d\x64\x41\x39\x08\xd3\x80\x38\x6b\xe3\x7f\x86\x2a\x30\x02\x72\x8c\xa6\x40\x39\x00\xd5\x7b\x5f\x2e\xfd\xba\xd5\x32\x00\x00\x00\x00\x49\x45\x4e\x44\xae\x42\x60\x82"
, 95, 0, 0, 639, 1135)
--
-- 示例 2：
img = image.load_file("/var/mobile/1.png")
x, y = screen.find_image(img)
x, y = screen.find_image(img, 95)
--
-- 示例 4：
x, y = screen.find_image("/var/mobile/1.png", 95, 0, 0, 639, 1135)

-- 示例 5（1.3.8 新增）这是全屏找多个目标
img = image.load_file(XXT_SCRIPTS_PATH..'/1.png')
rets = screen.find_image(img, {
    confidence_threshold = 90, -- 可信度大于这个值的结果有效
    downscale = 0.5, -- 降低精度提速
    find_all = true, -- 表示查找所有匹配项，返回所有匹配项的坐标表
}, 0, 0, 0, 0) -- 0, 0, 0, 0 区域表示全屏
```
**说明**：在 Lua 源码中，字符串中 `\x` 开头，后面跟两位 16 进制数表示以该数字编码的单个字节。例如：`\x58` 表示 `X` 这个字符，可打印字符部分参考[《ASCII 编码》](https://baike.baidu.com/item/ASCII/309296)


## 复杂示例

```lua
-- 从网上下载个小图片 (一部分 XXTouch 图标) 然后从屏幕上找到它并点击
local c, h, r = http.get("https://www.xxtouch.app/img/find_image_test.png", 10)
if (c == 200) then
    local img = image.load_data(r)
    if img then
        x, y = screen.find_image(img, 95)
        if x~=-1 then
            touch.tap(x, y)
        else
            sys.alert("没有在屏幕上找到 XXTouch 图标")
        end
    else
        sys.alert("下载的数据不是有效的图片")
    end
else
    sys.alert("下载失败")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`image.load_data`](/docs/handbook/image/image.load_data.md)、[`touch.tap`](/docs/handbook/touch/touch.tap.md)、[`http.get`](/docs/handbook/http/http.get.md)

---

Source: [输出标准系统日志 (sys.log)](https://xxtouch.app/docs/handbook/sys/sys.log.md)
Path: handbook/sys/sys.log.md

# 输出标准系统日志 (sys.log)


## 声明

```lua
sys.log(...)
```


## 参数

- ...
    任意个任意类型参数，代表需要输出的日志内容，参数之间使用 tab 分隔


## 说明

> 输出标准系统日志
> 日志可以使用电脑浏览器打开远程接口 **https://\<设备 IP 地址\>:46952/log.html** 实时查看
> 日志会同时存储到设备上的 **/var/mobile/Media/1ferver/log/sys.log** 文件中
> **/var/mobile/Media/1ferver/log/sys.log** 记录的日志最多不会超过 4000 行，超过则删前面的


## 示例

```lua
sys.log("Hello World")
```

---

Source: [查找一个 UI 元素 (ui_element.find)](https://xxtouch.app/docs/handbook/ui_element/ui_element.find.md)
Path: handbook/ui_element/ui_element.find.md

# 查找一个 UI 元素 (ui_element.find)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
元素, 错误信息 = ui_element.find(选择器 [, 选项 ])
```

## 参数

- 选择器
    表型，用于描述要查找的 UI 元素，可参考 [选择器字段说明](selector.md)。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 元素
    表型，第一个匹配的 UI 元素。失败时为 `nil`。
- 错误信息
    文本型，失败原因。没有匹配项时通常为 `"target not found"`。

## 说明

> 如果选择器中包含 `index`，则返回匹配结果中的第 `index` 个元素。
> 建议使用 `title` 或 `text_contains` 搭配 `role` 定位，减少同名元素带来的歧义。

## 示例

```lua
local ui_element = require("ui_element")

local item, err = ui_element.find({
    title = "搜索",
    role = "text_field",
})

if item then
    ui_element.click(item)
else
    sys.toast(err)
end
```

**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [RFC 1123 格式的时间文本转换为时间戳 (utils.date_from_rfc1123)](https://xxtouch.app/docs/handbook/utils/utils.date_from_rfc1123.md)
Path: handbook/utils/utils.date_from_rfc1123.md

# RFC 1123 格式的时间文本转换为时间戳 (utils.date_from_rfc1123)


## 声明

```lua
timestamp = utils.date_from_rfc1123(rfc1123)
```


## 参数

- rfc1123
    文本型，RFC 1123 格式的时间文本


## 返回值

- timestamp
    数值型，时间戳


## 说明

> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
nLog(utils.date_from_rfc1123("Mon, 09 Jun 2025 17:40:00 GMT")) -- 输出：1749490800.0
```

---

Source: [获取应用程序当前内存消耗 (app.used_memory)](https://xxtouch.app/docs/handbook/app/app.used_memory.md)
Path: handbook/app/app.used_memory.md

# 获取应用程序当前内存消耗 (app.used_memory)


## 声明

```lua
内存占用 = app.used_memory(应用包标识符 或 进程号)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
- 进程号
    整数型，需要检测的应用的进程号

## 返回值

- 内存占用
    实数型 或 nil，如果应用正在运行则返回其所占用的内存 \(单位 MB\) ，否则返回 nil


## 示例

```lua
local qqmem = app.used_memory("com.tencent.mqq")
sys.alert("当前QQ进程所占用的内存是："..qqmem.."MB")
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [设置设备名 (device.set_name)](https://xxtouch.app/docs/handbook/device/device.set_name.md)
Path: handbook/device/device.set_name.md

# 设置设备名 (device.set_name)


## 声明

```lua
device.set_name(名字)
```


## 参数

- 名字
    文本型，需要设置的设备名字


## 说明

> **注意：** 设置设备名可能在不同系统版本上存在不同程度的延迟生效现象。
> 即调用 device.set_name 后立即使用 device.name 获取到的可能仍是旧名称。
> 遇到此情况，请根据系统版本自行添加适当延迟后再读取。


## 示例

```lua
device.set_name("iPhavonz")
```

---

Source: [给对话框加上一个单选组 (:add_radio)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_radio.md)
Path: handbook/dialog/dialogm_add_radio.md

# 给对话框加上一个单选组 (:add_radio)


## 声明

```lua
对话框对象 = 对话框对象:add_radio(单选组标签, 选项列表 [, 默认选中项 ])
```


## 参数

- 单选组标签
    文本型，单选组标题标签显示的文本
- 选项列表
    表型，单选组的选项名顺序列表，选项名不允许重复
- 默认选中项
    文本型，可选参数，默认被选中的选项名，默认为选项列表的第一项

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    文本型，返回被选中的选项名


## 说明

> 给对话框加上一个单选组


## 示例

```lua
local c, s = dialog():add_radio('一个单选组', {'单选1', '单选2', '单选3'}):show()
sys.alert('你的选择是：'..s['一个单选组'])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [将一个顺序表转换逐行覆盖写入到文件中 (file.set_lines)](https://xxtouch.app/docs/handbook/file/file.set_lines.md)
Path: handbook/file/file.set_lines.md

# 将一个顺序表转换逐行覆盖写入到文件中 (file.set_lines)


## 声明

```lua
写入成败, 错误信息 = file.set_lines(文件路径, 行数组)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行数组
    顺序表型，需要转换写入到文件的表

## 返回值

- 写入成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将一个顺序表转换逐行覆盖写入到文件中，文件不存在会创建文件，目录不存在会返回 false
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local success, err = file.set_lines("/var/mobile/1.txt", {
    "苟利国家生死以",
    "岂因祸福避趋之",
})
if success then
    sys.alert("操作成功")
else
    sys.alert("操作失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取图片对象的 JPEG 格式数据 (:jpeg_data)](https://xxtouch.app/docs/handbook/image/imagem_jpeg_data.md)
Path: handbook/image/imagem_jpeg_data.md

# 获取图片对象的 JPEG 格式数据 (:jpeg_data)


## 声明

```lua
图片JPG数据 = 图片:jpeg_data([ 图像质量 ])
```


## 参数

- 图像质量
    实数型，可选参数，图片质量，取值范围 0.0~1.0，默认 1.0

## 返回值

- 图片 JPG 数据
    字符串型，返回 JPEG 数据，对这份数据的修改不会影响图片对象


## 说明

> 获取图片对象的 JPEG 格式数据
> 关键词：有损压缩、图像压缩、图片质量
> 性能上，该函数操作过程会产生两次数据拷贝


## 示例

```lua
-- 截全屏图像保存到文件并设置 JPEG 质量为 80%
file.writes('/var/mobile/1.jpg', screen.image():jpeg_data(0.8))
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)、[`file.writes`](/docs/handbook/file/file.writes.md)

---

Source: [! 使用硬件键盘输入文本 (:send_text)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_send_text.md)
Path: handbook/key/hardware_keyboardm_send_text.md

# ! 使用硬件键盘输入文本 (:send_text)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = 硬件键盘对象:send_text(文本[, 每键延迟, Shift键延迟])
```

## 参数

- 文本
    文本型，需要输入的文字；仅支持英文、数字、空格、半角字符以及 `"\b"`、`"\r"`、`"\t"`。
- 每键延迟
    实数型，可选参数，每个按键操作之间的延迟毫秒数，默认 0。
- Shift 键延迟
    实数型，可选参数，按下或松开 Shift 前后的延迟毫秒数，默认 0。

## 返回值

- 是否成功
    布尔型，全部文本发送成功时返回 `true`，失败时返回 `false`。
- 错误信息
    文本型，发送失败时返回错误信息。

## 说明

> 根据当前 Lua 的美式键盘映射生成按键和 Shift 组合。输入过程中的等待会隐式让出，在方法返回之前，其他[线程](/docs/handbook/thread/index.md)可能获得执行机会。

- 最终输入的字符仍受目标系统键盘布局影响。
- 本方法会保护调用前已经按下的普通键和修饰键。
- 同一硬件键盘正在执行 `:press` 或 `:send_text` 序列时，新的操作返回 `false, "hardware keyboard is busy"`。
- 发送失败时不会自动改用其它输入方式重试。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

assert(keyboard:send_text("Hello"))
assert(keyboard:send_text("Hello", 30, 10))

assert(keyboard:disconnect())
```

---

Source: [统计进程队列词典特定值个数 (proc_queue_count_value)](https://xxtouch.app/docs/handbook/proc/proc_queue_count_value.md)
Path: handbook/proc/proc_queue_count_value.md

# 统计进程队列词典特定值个数 (proc_queue_count_value)

## 声明

```lua
指定值个数 = proc_queue_count_value(键, 指定值)
```


## 参数

- 键
    字符串型
- 指定值
    字符串型，需要统计的值

## 返回值

- 指定值个数
    整数型，返回指定队列中的指定值的个数


## 说明

> **该函数在 20250106 以后的版本方可使用**
> **所有以 "xxtouch\." 或 "1ferver\." 开头的进程队列词典全部被保留**
> 统计进程队列词典特定值个数，返回特定值个数


## 示例

```lua
local count = proc_queue_count_value("billnos", "name")
if count ~= 0 then
    print(count)
else
    print("no bill")
end
```

---

Source: [坐标旋转转换 (screen.rotate_xy)](https://xxtouch.app/docs/handbook/screen/screen.rotate_xy.md)
Path: handbook/screen/screen.rotate_xy.md

# 坐标旋转转换 (screen.rotate_xy)


## 声明

```lua
旋转后的横坐标, 旋转后的纵坐标 = screen.rotate_xy(横坐标, 纵坐标, 旋转方向)
```


## 参数

- 横坐标, 纵坐标
    整数型，需要旋转的坐标
- **旋转方向**
    0 表示不旋转
    1 表示往左 90 度旋转
    2 表示往右 90 度旋转
    3 表示 180 度旋转


## 返回值

- 旋转后的横坐标, 旋转后的纵坐标
    整数型，返回使用 **旋转方向** 作为选项旋转后的坐标


## 说明

> 坐标旋转转换，通常用于将竖屏坐标转换成横屏坐标 `init(0) -> init(旋转方向)`


## 示例

```lua
rx, ry = screen.rotate_xy(100, 200, 1)
```

---

Source: [给指定进程号的进程发送信号 (sys.kill)](https://xxtouch.app/docs/handbook/sys/sys.kill.md)
Path: handbook/sys/sys.kill.md

# 给指定进程号的进程发送信号 (sys.kill)


## 声明

```lua
sys.kill(进程号, 信号)
```


## 参数

- 进程号
    整数型
- 信号
    整数型，信号编号


## 说明

> 发送信号给指定进程号


## 示例

```lua
-- 强制关闭前台应用
sys.kill(app.front_pid(), 9)
```
**注**：上述代码中使用了非本章函数 [`app.front_pid`](/docs/handbook/app/app.front_pid.md)

---

Source: [查找多个 UI 元素 (ui_element.find_all)](https://xxtouch.app/docs/handbook/ui_element/ui_element.find_all.md)
Path: handbook/ui_element/ui_element.find_all.md

# 查找多个 UI 元素 (ui_element.find_all)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
元素列表 = ui_element.find_all(选择器 [, 选项 ])
```

## 参数

- 选择器
    表型，用于描述要查找的 UI 元素，可参考 [选择器字段说明](selector.md)。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 元素列表
    表型，所有匹配元素组成的数组。没有匹配项时返回空数组。

## 说明

> `find_all` 适合枚举同类控件或先检查匹配数量。
> 如果只需要第一个匹配项，使用 [`find`](ui_element.find.md) 更直接。

## 示例

```lua
local ui_element = require("ui_element")

local items = ui_element.find_all({
    role = "button",
})

for i, item in ipairs(items) do
    nLog(i, item.text or "")
end
```

**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [时间戳转换为 RFC 3339 格式文本 (utils.date_to_rfc3339)](https://xxtouch.app/docs/handbook/utils/utils.date_to_rfc3339.md)
Path: handbook/utils/utils.date_to_rfc3339.md

# 时间戳转换为 RFC 3339 格式文本 (utils.date_to_rfc3339)


## 声明

```lua
rfc3339 = utils.date_to_rfc3339(timestamp)
```


## 参数

- timestamp
    数值型，时间戳


## 返回值

- rfc3339
    文本型，RFC 3339 格式的时间文本


## 说明

> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
nLog(utils.date_to_rfc3339(1749490800)) -- 输出：2025-06-09T17:40:00.000Z
nLog(utils.date_to_rfc3339(os.time())) -- 输出类似：2025-06-09T17:40:00.000Z
```

---

Source: [获取前台应用的包标识符 (app.front_bid)](https://xxtouch.app/docs/handbook/app/app.front_bid.md)
Path: handbook/app/app.front_bid.md

# 获取前台应用的包标识符 (app.front_bid)


## 声明

```lua
应用包标识符 = app.front_bid()
```


## 返回值

- 应用包标识符
    文本型，返回前台应用的应用包标识符
    没有应用处于前台但桌面 (SpringBoard) 已加载，返回 `"com.apple.springboard"`
    没有应用处于前台且 SpringBoard 尚未启动（系统引导早期），返回后台服务 `"com.apple.backboardd"`


## 说明

> 获取前台应用的应用包标识符


## 示例

```lua
local bid = app.front_bid()
sys.alert("前台应用的应用包标识符是："..bid)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取设备 UDID (device.udid)](https://xxtouch.app/docs/handbook/device/device.udid.md)
Path: handbook/device/device.udid.md

# 获取设备 UDID (device.udid)


## 声明

```lua
udid = device.udid()
```


## 返回值

- udid
    文本型，返回设备的 UDID


## 说明

> UDID 参考资料：[The iPhone Wiki - UDID](https://www.theiphonewiki.com/wiki/UDID)


## 示例

```lua
sys.alert("设备的 UDID 是："..device.udid())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [给对话框加上一个多选组 (:add_checkbox)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_checkbox.md)
Path: handbook/dialog/dialogm_add_checkbox.md

# 给对话框加上一个多选组 (:add_checkbox)


## 声明

```lua
对话框对象 = 对话框对象:add_checkbox(多选组标签, 选项列表 [, 默认选中项 ])
```


## 参数

- 多选组标签
    文本型，多选组标题标签显示的文本
- 选项列表
    表型，多选组的选项名顺序列表，选项名不允许重复
- 默认选中项
    表型，可选参数，默认选中的选项名列表，默认为空表

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    表型，一个包含所有被选中项的顺序表


## 说明

> 给对话框加上一个多选组


## 示例

```lua
local c, s = dialog()
:add_checkbox('一个多选组', {'选项1', '选项2', '选项3', '选项4'}, {'选项1', '选项3'})
:show()
print('一共选中了 '..#(s['一个多选组'])..' 个选项')
print('选中列表如下')
for _, oname in ipairs(s['一个多选组']) do
    print(oname)
end
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`print`](/docs/handbook/develop-helper/print.md)、[`print.out`](/docs/handbook/develop-helper/print.out.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [将一个顺序表转换逐行插入到文件指定行前 (file.insert_lines)](https://xxtouch.app/docs/handbook/file/file.insert_lines.md)
Path: handbook/file/file.insert_lines.md

# 将一个顺序表转换逐行插入到文件指定行前 (file.insert_lines)


## 声明

```lua
写入成败, 错误信息 = file.insert_lines(文件路径, 行号, 行数组)
```


## 参数

- 文件路径
    文本型，文件绝对路径
- 行号
    整数型，指定行号，0 为最后一行 \+1，负数则为倒数行号
- 行数组
    顺序表型，需要转换插入到文件的表

## 返回值

- 写入成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将一个顺序表转换逐行插入到文件指定行前，文件不存在会创建文件，目录不存在会返回 false
> 该函数会自动剔除掉文件头部的 UTF8-BOM


## 示例

```lua
local success = file.insert_lines("/var/mobile/1.txt", 0, { -- 将下面两行字追加到文件末尾
    "I will do whatever it takes to serve my country even at the cost of my own life,",
    "regardless of fortune or misfortune to myself.",
})
if success then
    sys.alert("操作成功")
else
    sys.alert("操作失败")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [90 度左旋图片对象 (:turn_left)](https://xxtouch.app/docs/handbook/image/imagem_turn_left.md)
Path: handbook/image/imagem_turn_left.md

# 90 度左旋图片对象 (:turn_left)


## 声明

```lua
图像 = 图像:turn_left()
```


## 返回值

- 图像
    图片对象，返回图片对象本体


## 说明

> 90 度左旋图片对象
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝

---

Source: [判断硬件键盘是否已连接 (:is_connected)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_is_connected.md)
Path: handbook/key/hardware_keyboardm_is_connected.md

# 判断硬件键盘是否已连接 (:is_connected)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否已连接 = 硬件键盘对象:is_connected()
```

## 返回值

- 是否已连接
    布尔型，对象仍连接且可以操作时返回 `true`，已经断开时返回 `false`。

## 说明

> 获取当前硬件键盘对象的连接状态。

全局硬件键盘断开后，原对象仍可被 Lua 变量持有，但本方法会返回 `false`，并且 [`key.get_global_keyboard`](key.get_global_keyboard.md) 返回 `nil`。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

local connected = keyboard:is_connected()
local properties = keyboard:get_properties()
local success, err = keyboard:disconnect()
assert(success, err)
```

---

Source: [执行进程词典事务代码 (proc_dict_run)](https://xxtouch.app/docs/handbook/proc/proc_dict_run.md)
Path: handbook/proc/proc_dict_run.md

# 执行进程词典事务代码 (proc_dict_run)


## 声明

```lua
返回内容, 错误信息 = proc_dict_run(事务代码)
```


## 参数

- 事务代码
    字符串型，需要执行的事务 Lua 代码

## 返回值

- 返回内容
    字符串型 | nil，执行成功返回代码返回的值，执行失败返回 nil
- 错误信息
    文本型 | nil，执行成功返回 nil，执行代码发生错误时返回错误信息


## 说明

> **该函数在 20250427 以后的版本方可使用**
> **所有以 "xxtouch\." 或 "1ferver\." 开头的进程队列词典全部被保留**
> 执行进程词典事务代码，事务代码执行期间，将阻止其它线程访问 proc_ 函数执行
> 单次运行最多不能超过 1000000 行
> 如果执行成功，这段 Lua 代码可以返回一个字符串值
>    该字符串值将作为返回值返回给调用者
>    如果代码返回 nil，则会返回空字符串给调用者
> 如果执行失败，将返回 nil, 错误信息

<details>

<summary>运行事务 Lua 代码可以使用如下模块以及如下函数</summary>

base 模块（不包含 require）
table 模块
string 模块
math 模块
utf8 模块
bit32 模块
json 模块
os.time()
os.clock()
sys.mtime()
utils.gen_uuid()
proc_put(key, value)
proc_get(key)
proc_queue_push_back(key, value)
proc_queue_push_front(key, value)
proc_queue_pop_front(key)
proc_queue_pop_back(key)
proc_queue_pop_value(key, value)
proc_queue_count_value(key, value)
proc_queue_clear(key)
proc_queue_read(key)
proc_queue_size(key)

</details>


## 示例

```lua
function proc_inc(key, int_value)
    return proc_dict_run(string.format([[
        local key = %q
        local value = %d
        local ov = proc_get(key)
        if ov == '' then
            ov = 0
        else
            ov = tonumber(ov)
        end
        if not ov then
            error('not a number')
        end
        proc_put(key, tostring(ov + value))
        return ov
    ]], key, int_value))
end

for i = 1, 20 do
    nLog(proc_inc('haha', 10))
end
```

---

Source: [反向坐标旋转转换 (screen.unrotate_xy)](https://xxtouch.app/docs/handbook/screen/screen.unrotate_xy.md)
Path: handbook/screen/screen.unrotate_xy.md

# 反向坐标旋转转换 (screen.unrotate_xy)


## 声明

```lua
对应的竖屏横坐标, 对应的竖屏纵坐标 = screen.unrotate_xy(原横坐标, 原纵坐标, 原坐标旋转方向)
```


## 参数

- 原横坐标, 原纵坐标
    整数型，需要转换回竖屏坐标的坐标
- **原坐标旋转方向**
    0 表示原坐标是竖屏 Home 向下，这种情况直接返回原值
    1 表示原坐标是横屏 Home 向右
    2 表示原坐标是横屏 Home 向左
    3 表示原坐标是竖屏 Home 向上


## 返回值

- 对应的竖屏横坐标, 对应的竖屏纵坐标
    整数型，返回使用 **原坐标旋转方向** 的坐标对应的竖屏坐标


## 说明

> 坐标旋转转换，通常用于将横屏坐标转换回竖屏坐标 `init(原坐标旋转方向) -> init(0)`
> **软件版本在 1.3.8 或以上方可使用**


## 示例

```lua
rx, ry = screen.unrotate_xy(100, 200, 1) -- 将横屏坐标 (100, 200) 转换回竖屏坐标
```

---

Source: [发送信号给指定名称的进程 (sys.killall)](https://xxtouch.app/docs/handbook/sys/sys.killall.md)
Path: handbook/sys/sys.killall.md

# 发送信号给指定名称的进程 (sys.killall)


## 声明

```lua
sys.killall(信号, [进程名称1, 进程名称2, ...])
```


## 参数

- 信号
    整数型，信号编号
- 进程名称 1, 进程名称 2, ...
    文本型，进程名称，可选参数，可指定多个进程名称


## 说明

> 发送信号给指定名称的进程
> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
-- 注销设备
sys.killall(9, "SpringBoard", "backboardd")
```

---

Source: [获取一次 UI 快照 (ui_element.snapshot)](https://xxtouch.app/docs/handbook/ui_element/ui_element.snapshot.md)
Path: handbook/ui_element/ui_element.snapshot.md

# 获取一次 UI 快照 (ui_element.snapshot)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
快照, 错误信息 = ui_element.snapshot([ 选项 ])
```

## 参数

- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

**20261115 起**支持[属性排除选项](options.md#attribute-exclusions)。

## 返回值

- 快照
    表型，包含当前 UI 元素列表和快照方法。失败时为 `nil`。
- 错误信息
    文本型，失败原因。

## 快照方法

```lua
元素 = 快照:find(选择器)
元素列表 = 快照:find_all(选择器)
状态, 信息 = 快照:click(选择器或元素 [, 选项 ])
状态, 信息 = 快照:scroll([ 选择器或元素, ] 方向 [, 选项 ])
状态, 信息 = 快照:input_text(选择器或元素, 文本 [, 选项 ])
状态, 信息 = 快照:set_text(选择器或元素, 文本 [, 选项 ])
状态, 信息 = 快照:clear_text(选择器或元素 [, 选项 ])
状态, 信息 = 快照:toggle(选择器或元素 [, 选项 ])
状态, 信息 = 快照:set_checked(选择器或元素, 勾选状态 [, 选项 ])
状态, 信息 = 快照:set_value(选择器或元素, 值 [, 选项 ])
状态, 信息 = 快照:increase(选择器或元素 [, 选项 ])
状态, 信息 = 快照:decrease(选择器或元素 [, 选项 ])
```

## 说明

> 快照是一次性结果，适合在同一界面内多次查找或连续操作。
> 界面发生跳转、弹窗、滚动或内容刷新后，应重新调用 `snapshot()`。
> 快照表常见字段包括 `elements` 和 `count`。

## 示例

```lua
local ui_element = require("ui_element")

local ui, err = ui_element.snapshot({
    max_level = 2,
})

if ui then
    local search = ui:find({
        title = "搜索",
        role = "text_field",
    })
    if search then
        ui:set_text(search, "XXTouch")
    end
else
    sys.toast(err)
end
```

**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [RFC 3339 格式的时间文本转换为时间戳 (utils.date_from_rfc3339)](https://xxtouch.app/docs/handbook/utils/utils.date_from_rfc3339.md)
Path: handbook/utils/utils.date_from_rfc3339.md

# RFC 3339 格式的时间文本转换为时间戳 (utils.date_from_rfc3339)


## 声明

```lua
timestamp = utils.date_from_rfc3339(rfc3339)
```


## 参数

- rfc3339
    文本型，RFC 3339 格式的时间文本


## 返回值

- timestamp
    数值型，时间戳


## 说明

> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
nLog(utils.date_from_rfc3339("2025-06-09T17:40:00.000Z")) -- 输出：1749490800.0
```

---

Source: [获取前台应用的进程号 (app.front_pid)](https://xxtouch.app/docs/handbook/app/app.front_pid.md)
Path: handbook/app/app.front_pid.md

# 获取前台应用的进程号 (app.front_pid)


## 声明

```lua
进程号 = app.front_pid()
```


## 返回值

- 进程号
    整数型，返回前台应用的进程号，前台没有应用返回 0


## 说明

> 获取前台应用的进程号
> 前台没有应用时返回 0，而不是返回 SpringBoard（桌面）的进程号
> 如需获取 SpringBoard 的进程号，请使用
```lua
local desktop_pid = app.pid_for_bid('com.apple.springboard')
sys.alert("桌面服务的进程号是："..desktop_pid)
```


## 示例

```lua
local pid = app.front_pid()
sys.alert("前台应用的进程号是："..pid)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取设备的序列号 (device.serial_number)](https://xxtouch.app/docs/handbook/device/device.serial_number.md)
Path: handbook/device/device.serial_number.md

# 获取设备的序列号 (device.serial_number)


## 声明

```lua
序列号 = device.serial_number()
```


## 返回值

- 序列号
    文本型，返回设备的序列号


## 示例

```lua
sys.alert("设备的序列号是："..device.serial_number())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [给对话框加上一个数值选择器 (:add_range)](https://xxtouch.app/docs/handbook/dialog/dialogm_add_range.md)
Path: handbook/dialog/dialogm_add_range.md

# 给对话框加上一个数值选择器 (:add_range)


## 声明

```lua
对话框对象 = 对话框对象:add_range(范围选择器标签, 范围选择器参数 [, 默认位置 ])
```


## 参数

- 范围选择器标签
    文本型，数值选择器标题标签显示的文本
- 范围选择器参数
    表型，用于描述范围与步进的表，格式为 `{最小值, 最大值, 步进值}`
    - 最小值
        实数型，为数值选择条最左边的位置
    - 最大值
        实数型，为数值选择条最右边的位置
    - 步进值
        实数型，可选参数，为选择条拖动的最小单位，默认为 1
- 默认位置
    实数型，可选参数，默认值，默认为最小值

## 返回值

- 对话框对象
    对话框，返回对话框本身
- 使用 :show() 时返回类型
    实数型，返回用户选择的数值


## 说明

> 给对话框加上一个数值选择器


## 示例

```lua
local c, s = dialog():add_range('一个数值', {222, 666, 1}, 333):show()
sys.alert('数值是：'..s['一个数值'])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 完整示例

[`本章结尾 :show()`](/docs/handbook/dialog/dialogm_show.md)

---

Source: [获得一个文件的 MD5 值 (file.md5)](https://xxtouch.app/docs/handbook/file/file.md5.md)
Path: handbook/file/file.md5.md

# 获得一个文件的 MD5 值 (file.md5)


## 声明

```lua
MD5值, 错误信息 = file.md5(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- MD5 值
    文本型 或 nil，如果文件不存在或文件名是一个目录则返回 nil，否则返回文件 MD5 值
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获得一个文件的 MD5 值


## 示例

```lua
local md5, err = file.md5("/var/mobile/1.zip")
if md5 then
    sys.alert("`/var/mobile/1.zip` 的 MD5 值为："..md5)
else
    sys.alert("`/var/mobile/1.zip` 不是文件："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [90 度右旋图片对象 (:turn_right)](https://xxtouch.app/docs/handbook/image/imagem_turn_right.md)
Path: handbook/image/imagem_turn_right.md

# 90 度右旋图片对象 (:turn_right)


## 声明

```lua
图像 = 图像:turn_right()
```


## 返回值

- 图像
    图片对象，返回图片对象本体


## 说明

> 90 度右旋图片对象
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝

---

Source: [获取硬件键盘配置属性 (:get_properties)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_get_properties.md)
Path: handbook/key/hardware_keyboardm_get_properties.md

# 获取硬件键盘配置属性 (:get_properties)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
配置属性 = 硬件键盘对象:get_properties()
```

## 返回值

- 配置属性
    表型，创建设备时保存的配置属性副本。

## 说明

> `get_properties()` 返回创建时保存的配置副本，其中可能包含由系统管理的属性。它不是实时系统状态，iOS 实际采用的值可能不同。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

local properties = keyboard:get_properties()
print(properties.Product)
print(properties.Transport)

assert(keyboard:disconnect())
```

---

Source: [递归修改文件所有者 (sys.lchown_r)](https://xxtouch.app/docs/handbook/sys/sys.lchown_r.md)
Path: handbook/sys/sys.lchown_r.md

# 递归修改文件所有者 (sys.lchown_r)


## 声明

```lua
sys.lchown_r(文件路径, 用户ID, 用户组ID)
```


## 参数

- 文件路径
    文本型
- 用户 ID
    整数型
- 用户组 ID
    整数型


## 说明

> 将对目录下所有文件和子目录递归修改所有者，不会遍历深层符号链接指向的目录
> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
sys.lchown_r("/var/mobile/Media/1ferver", 501, 501)
```

---

Source: [时间戳转换为格式的时间文本 (utils.date_to_format)](https://xxtouch.app/docs/handbook/utils/utils.date_to_format.md)
Path: handbook/utils/utils.date_to_format.md

# 时间戳转换为格式的时间文本 (utils.date_to_format)


## 声明

```lua
date = utils.date_to_format(format, timestamp[, options])
```


## 参数

- format
    文本型，时间格式
- timestamp
    数值型，时间戳
- options
    表型，选项表
    ```lua
    {
        tz = "GMT";       -- 时区选项，可选参数，默认为系统时区；时区列表可参考 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
        locale = "en-US"; -- 本地化选项，可选参数，默认为当前设备的区域设置
    }
    ```


## 返回值

- date
    文本型，格式化后的时间字符串


## 说明

> **该函数在 20250220 以后版本方可使用**


## 格式参考

[Unicode Date Field Symbol Table](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table)

| 分类 | 占位符 | 示例输出 | 描述 |
| :--- | :--- | :--- | :--- |
| **年份 (Year)** | `yyyy` | `2024` | 4位数的年份 |
| | `yy` | `24` | 2位数的年份 |
| **月份 (Month)** | `MMMM` | `July` | 月份的全名 |
| | `MMM` | `Jul` | 月份的缩写 |
| | `MM` | `07` | 2位数的月份 (01-12) |
| | `M` | `7` | 1位或2位数的月份 |
| **日期 (Day)** | `dd` | `06` | 2位数的日期 (01-31) |
| | `d` | `6` | 1位或2位数的日期 |
| **星期 (Day of Week)**| `EEEE` | `Saturday` | 星期几的全名 |
| | `E`, `EE`, `EEE`| `Sat` | 星期几的缩写 |
| | `e`, `ee` | `7` | 本地化的星期几数字 (周日=1, 周六=7) |
| **小时 (Hour)** | `HH` | `15` | 24小时制的2位数小时 (00-23) |
| | `H` | `15` | 24小时制的1或2位数小时 |
| | `hh` | `03` | 12小时制的2位数小时 (01-12) |
| | `h` | `3` | 12小时制的1或2位数小时 |
| | `a` | `PM` | 上午/下午标记 (AM/PM) |
| **分钟 (Minute)** | `mm` | `05` | 2位数的分钟 (00-59) |
| | `m` | `5` | 1或2位数的分钟 |
| **秒 (Second)** | `ss` | `09` | 2位数的秒 (00-59) |
| | `S` | `.1` `.12` `.123`| 毫秒。S 的数量决定了小数位数。 |
| **时区 (Time Zone)** | `zzzz` | `Pacific Daylight Time` | 时区的全名 |
| | `zzz`, `z` | `PDT` | 时区的缩写 |
| | `ZZZZZ` | `-07:00` | ISO 8601 格式的时区偏移，带冒号 |
| | `Z`, `ZZ`, `ZZZ` | `-0700` | RFC 822 格式的时区偏移 |


## 示例

```lua
nLog(utils.date_to_format("EEE, dd MMM yyyy HH:mm:ss ZZZZ", 1749490800, {tz = "PST"; locale = 'en-US'})) -- 输出：Mon, 09 Jun 2025 10:40:00 GMT-07:00
nLog(utils.date_to_format("EEE, dd MMM yyyy HH:mm:ss ZZZZ", 1749490800, {tz = "PST"; locale = 'zh-CN'})) -- 输出：周一, 09 6月 2025 10:40:00 GMT-07:00
```

---

Source: [前台打开一个 URL (app.open_url)](https://xxtouch.app/docs/handbook/app/app.open_url.md)
Path: handbook/app/app.open_url.md

# 前台打开一个 URL (app.open_url)


## 声明

```lua
ok = app.open_url(URL)
```


## 参数

- URL
    文本型，需要打开的 URL ，可以打开 [URL Scheme](https://developer.apple.com/library/ios/featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html) \([“URL Scheme” 的相关应用](/docs/handbook/supplement/url-scheme.md)\)


## 返回值

- ok
    布尔型，是否成功打开 URL


## 说明

> 前台打开一个 URL，可以打开 [URL Scheme](https://developer.apple.com/library/ios/featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html) \([“URL Scheme” 的相关应用](/docs/handbook/supplement/url-scheme.md)\)
> 对于部分 URL，使用该 API 跳转可能达不到预期效果，可在越狱环境下改用 uiopen 命令
```lua
local function sh_escape(path) -- XXTouch 原创函数，无需 XXTouch 许可即可用于商业用途
    path = string.gsub(path, "([ \\()<>'\"`#&*;?~$|])", "\\%1")
    return path
end
os.execute('uiopen '..sh_escape('https://www.google.com'))
os.execute('uiopen '..sh_escape('prefs:root=SAFARI&path=CLEAR_HISTORY_AND_DATA'))
```


## 示例

```lua
app.open_url("https://www.google.com") -- 用 Safari 打开 Google 的主页
--
app.open_url("prefs:root=SAFARI&path=CLEAR_HISTORY_AND_DATA") -- 跳转到 设置 -> Safari 浏览器 -> 清除历史记录与网站数据
```

---

Source: [获取设备的 WiFi MAC 地址 (device.wifi_mac)](https://xxtouch.app/docs/handbook/device/device.wifi_mac.md)
Path: handbook/device/device.wifi_mac.md

# 获取设备的 WiFi MAC 地址 (device.wifi_mac)


## 声明

```lua
Wi-Fi MAC 地址 = device.wifi_mac()
```


## 返回值

- Wi-Fi MAC 地址
    文本型，返回设备的 WiFi MAC 地址


## 示例

```lua
sys.alert("设备的 WiFi MAC 地址是："..device.wifi_mac())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [! 将对话框弹出来并返回用户的选择 (:show)](https://xxtouch.app/docs/handbook/dialog/dialogm_show.md)
Path: handbook/dialog/dialogm_show.md

# ! 将对话框弹出来并返回用户的选择 (:show)


## 声明

```lua
是否提交, 选项关联表 = 对话框对象:show()
```


## 返回值

- 是否提交
    布尔型，返回是否按下了提交按钮；超时或点击右上角 **×** 返回 false
- 选项关联表
    表型，返回一个以选项标签映射的键值表


## 说明

> 将对话框弹出，并返回用户的选择结果
> 如果对话框设置了配置保存 (:set_config(配置名))，按下 **提交** 会保存配置；按右上角的 **×** 或超时则不保存


## 简单示例

```lua
local c, s = dialog():add_switch('一个开关', false):show()
sys.alert(s["一个开关"])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 复杂示例

```lua
local dlg = dialog() -- 创建一个 dialog 对象
--
-- 以下为此 dialog 对象配置
dlg:set_config('test') -- 配置保存ID
dlg:set_timeout(30)
dlg:add_label('简易的效果展示')
dlg:add_range('血量', {0, 1000, 1}, 300)
dlg:add_input('账号', 'ccc')
dlg:add_input('密码', 'aaaa')
dlg:add_picker('性别', {'男', '女', '未知'}, '男')
dlg:add_switch('启用通知', false)
dlg:add_checkbox('喜欢的游戏', {'守望先锋', '魔兽世界', '炉石传说'}, {'守望先锋', '魔兽世界'})
dlg:add_radio('最喜欢的游戏', {'守望先锋', '魔兽世界', '炉石传说'}, '魔兽世界')
--
local confirm, selects = dlg:show() -- 显示 dialog 对象到前台并获得其返回值
--
if (confirm) then
    print("你按下了提交")
else
    print("你没有按下提交")
end
--
print("账号", selects["账号"])
print("密码", selects["密码"])
print("性别", selects["性别"])
print("血量", selects["血量"])
--
if (selects['启用通知']) then
    print("已启用通知")
else
    print("未启用通知")
end
--
print("你喜欢游戏列表")
for _,gamename in ipairs(selects['喜欢的游戏']) do
    print(gamename)
end
--
print("你最喜欢游戏:"..selects["最喜欢的游戏"])
--
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`print`](/docs/handbook/develop-helper/print.md)、[`print.out`](/docs/handbook/develop-helper/print.out.md)

---

Source: [获得一个文件的 SHA1 值 (file.sha1)](https://xxtouch.app/docs/handbook/file/file.sha1.md)
Path: handbook/file/file.sha1.md

# 获得一个文件的 SHA1 值 (file.sha1)


## 声明

```lua
SHA1值, 错误信息 = file.sha1(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- SHA1 值
    文本型 或 nil，如果文件不存在或文件名是一个目录则返回 nil，否则返回文件 SHA1 值
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获得一个文件的 SHA1 值


## 示例

```lua
local sha1, err = file.sha1("/var/mobile/1.zip")
if sha1 then
    sys.alert("`/var/mobile/1.zip` 的 SHA1 值为："..sha1)
else
    sys.alert("`/var/mobile/1.zip` 不是文件："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取图片对象的尺寸 (:size)](https://xxtouch.app/docs/handbook/image/imagem_size.md)
Path: handbook/image/imagem_size.md

# 获取图片对象的尺寸 (:size)


## 声明

```lua
宽, 高 = 图像:size()
```


## 返回值

- 宽, 高
    整数型，当前操作的图片对象的 宽、高


## 说明

> 获取图片对象的尺寸，注意这里返回的宽不一定比高短，旋转会发生改变


## 示例

```lua
local img = image.load_file("/var/mobile/1.png")
local w, h = img:size()
sys.alert("图像的宽："..w.."\n图像的高："..h)
```

---

Source: [断开硬件键盘 (:disconnect)](https://xxtouch.app/docs/handbook/key/hardware_keyboardm_disconnect.md)
Path: handbook/key/hardware_keyboardm_disconnect.md

# 断开硬件键盘 (:disconnect)

> **该方法在 20260805 以后版本方可使用**

## 声明

```lua
是否成功, 错误信息 = 硬件键盘对象:disconnect()
```

## 返回值

- 是否成功
    布尔型，断开成功时返回 `true`，失败时返回 `false`。
- 错误信息
    文本型，断开失败时返回错误信息。

## 说明

> 释放全部按键并断开该硬件键盘对象。

- 本方法可以重复调用。
- 对象是当前全局硬件键盘时，本方法也会清除全局键盘连接。
- 同一硬件键盘正在执行 `:press` 或 `:send_text` 序列时，本方法返回 `false, "hardware keyboard is busy"`。
- Lua 回收硬件键盘对象或脚本停止时，XXTouch 同样会自动释放全部按键并断开对象。

## 示例

```lua
local keyboard = assert(key.connect_keyboard())

local success, err = keyboard:disconnect()
assert(success, err)
```

---

Source: [递归修改文件权限 (sys.lchmod_r)](https://xxtouch.app/docs/handbook/sys/sys.lchmod_r.md)
Path: handbook/sys/sys.lchmod_r.md

# 递归修改文件权限 (sys.lchmod_r)


## 声明

```lua
sys.lchmod_r(文件路径, 权限)
```


## 参数

- 文件路径
    文本型
- 权限
    整数型，权限值，例如八进制 `0755` 等价于 `7 * 8^2 | 5 * 8^1 | 5`
    文本型，权限值，例如 `"0755"` 或 `"rwxr-xr-x"`（自 20250625 版本起支持）


## 说明

> 将对目录下所有文件和子目录递归修改权限，不会遍历深层符号链接指向的目录
> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
sys.lchmod_r("/var/mobile/Media/1ferver", 7 * 8^2 | 5 * 8^1 | 5)

-- 20250625 以上版本支持以下两种形式参数
sys.lchmod_r("/var/mobile/Media/1ferver", "0755")
sys.lchmod_r("/var/mobile/Media/1ferver", "rwxr-xr-x")
```

---

Source: [格式的时间文本转换为时间戳 (utils.date_from_format)](https://xxtouch.app/docs/handbook/utils/utils.date_from_format.md)
Path: handbook/utils/utils.date_from_format.md

# 格式的时间文本转换为时间戳 (utils.date_from_format)


## 声明

```lua
timestamp = utils.date_from_format(format, date[, options])
```


## 参数

- format
    文本型，时间格式
- date
    文本型，时间字符串
- options
    表型，选项表
    ```lua
    {
        tz = "GMT";       -- 时区选项，可选参数，默认为系统时区；时区列表可参考 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
        locale = "en-US"; -- 本地化选项，可选参数，默认为当前设备的区域设置
    }
    ```


## 返回值

- timestamp
    数值型，时间戳


## 说明

> **该函数在 20250220 以后版本方可使用**


## 格式参考

[Unicode Date Field Symbol Table](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table)

| 分类 | 占位符 | 示例输出 | 描述 |
| :--- | :--- | :--- | :--- |
| **年份 (Year)** | `yyyy` | `2024` | 4位数的年份 |
| | `yy` | `24` | 2位数的年份 |
| **月份 (Month)** | `MMMM` | `July` | 月份的全名 |
| | `MMM` | `Jul` | 月份的缩写 |
| | `MM` | `07` | 2位数的月份 (01-12) |
| | `M` | `7` | 1位或2位数的月份 |
| **日期 (Day)** | `dd` | `06` | 2位数的日期 (01-31) |
| | `d` | `6` | 1位或2位数的日期 |
| **星期 (Day of Week)**| `EEEE` | `Saturday` | 星期几的全名 |
| | `E`, `EE`, `EEE`| `Sat` | 星期几的缩写 |
| | `e`, `ee` | `7` | 本地化的星期几数字 (周日=1, 周六=7) |
| **小时 (Hour)** | `HH` | `15` | 24小时制的2位数小时 (00-23) |
| | `H` | `15` | 24小时制的1或2位数小时 |
| | `hh` | `03` | 12小时制的2位数小时 (01-12) |
| | `h` | `3` | 12小时制的1或2位数小时 |
| | `a` | `PM` | 上午/下午标记 (AM/PM) |
| **分钟 (Minute)** | `mm` | `05` | 2位数的分钟 (00-59) |
| | `m` | `5` | 1或2位数的分钟 |
| **秒 (Second)** | `ss` | `09` | 2位数的秒 (00-59) |
| | `S` | `.1` `.12` `.123`| 毫秒。S 的数量决定了小数位数。 |
| **时区 (Time Zone)** | `zzzz` | `Pacific Daylight Time` | 时区的全名 |
| | `zzz`, `z` | `PDT` | 时区的缩写 |
| | `ZZZZZ` | `-07:00` | ISO 8601 格式的时区偏移，带冒号 |
| | `Z`, `ZZ`, `ZZZ` | `-0700` | RFC 822 格式的时区偏移 |


## 示例

```lua
nLog(utils.date_from_format("EEE, dd MMM yyyy HH:mm:ss ZZZZ", "Mon, 09 Jun 2025 17:40:00 GMT", {tz = "GMT"; locale = 'en-US'})) -- 输出：1749490800.0
```

---

Source: [获取设备所有的应用的包标识符列表 (app.bundles)](https://xxtouch.app/docs/handbook/app/app.bundles.md)
Path: handbook/app/app.bundles.md

# 获取设备所有的应用的包标识符列表 (app.bundles)


## 声明

```lua
应用包标识符数组 = app.bundles()
```


## 返回值

- 应用包标识符数组
    顺序表型，返回包含设备上所有应用包标识符的表（包含系统自带应用）


## 说明

> 获取设备所有的应用的应用包标识符列表


## 示例

```lua
-- 遍历关闭所有的 app
for _,bid in ipairs(app.bundles()) do
    app.close(bid)
end
```

---

Source: [获取当前 Wi-Fi 的信息 (device.wifi_info)](https://xxtouch.app/docs/handbook/device/device.wifi_info.md)
Path: handbook/device/device.wifi_info.md

# 获取当前 Wi-Fi 的信息 (device.wifi_info)


## 声明

```lua
Wi-Fi 信息 = device.wifi_info()
```


## 返回值

- Wi-Fi 信息
    表型 | nil，成功返回一个特定结构的表，失败返回 nil
    <details>

    <summary>展开结构</summary>

    ```lua
    {
        SSID = string_value,
        BSSID = string_value,
        hidden = boolean_value,
        encryption = string_value,
        password = string_value,
        channel = integer_value,
    }
    ```
    </details>

## 说明

> **软件版本在 1.3.8 或以上方可使用**

## 示例

```lua
nLog(device.wifi_info())
```

---

Source: [! 在不弹出对话框的情况下获得对话框配置 (:load)](https://xxtouch.app/docs/handbook/dialog/dialogm_load.md)
Path: handbook/dialog/dialogm_load.md

# ! 在不弹出对话框的情况下获得对话框配置 (:load)


## 声明

```lua
是否提交, 选项关联表 = 对话框对象:load()
```


## 返回值

- 是否提交
    布尔型，为兼容 :show 的返回格式保留；该方法始终返回 false
- 选项关联表
    表型，返回一个以选项标签映射的键值表


## 说明

> 在不弹出对话框的情况下获得对话框配置，如果对话框当前没有保存配置，则加载默认值


## 示例

```lua
local dlg = dialog()
--
dlg:set_config('test') -- 配置保存ID
dlg:set_timeout(30)
dlg:add_label('简易的效果展示')
dlg:add_range('血量', {0, 1000, 1}, 300)
dlg:add_input('账号', 'ccc')
dlg:add_input('密码', 'aaaa')
dlg:add_picker('性别', {'男', '女', '未知'}, '男')
dlg:add_switch('启用通知', false)
dlg:add_checkbox('喜欢的游戏', {'守望先锋', '魔兽世界', '炉石传说'}, {'守望先锋', '魔兽世界'})
dlg:add_radio('最喜欢的游戏', {'守望先锋', '魔兽世界', '炉石传说'}, '魔兽世界')
--
local _, selects
--
if (utils.is_launch_via_app()) then -- 判断当前是否从 app 启动
    _, selects = dlg:show()         -- 从 app 启动的脚本则弹出配置窗
else
    _, selects = dlg:load()         -- 音量键或其它方式启动的脚本则不再弹出
end
--
print("账号", selects["账号"])
print("密码", selects["密码"])
print("性别", selects["性别"])
print("血量", selects["血量"])
--
if (selects['启用通知']) then
    print("已启用通知")
else
    print("未启用通知")
end
--
print("你喜欢游戏列表")
for _,gamename in ipairs(selects['喜欢的游戏']) do
    print(gamename)
end
--
print("你最喜欢游戏:"..selects["最喜欢的游戏"])
--
sys.alert(print.out())
```
**注**：上述代码中使用了非本章函数 [`utils.is_launch_via_app`](/docs/handbook/utils/utils.is_launch_via_app.md)、 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`print`](/docs/handbook/develop-helper/print.md)、[`print.out`](/docs/handbook/develop-helper/print.out.md)

---

Source: [删除文件或目录 (file.remove)](https://xxtouch.app/docs/handbook/file/file.remove.md)
Path: handbook/file/file.remove.md

# 删除文件或目录 (file.remove)


## 声明

```lua
操作成败, 错误信息 = file.remove(文件路径)
```


## 参数

- 文件路径
    文本型，文件绝对路径

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 删除一个文件或目录
> 关键词：删除文件、删除目录、删除文件夹
> **该函数在 20250313 以后的版本方可使用**


## 示例

```lua
ok, err = file.remove(XXT_SCRIPTS_PATH.."/1.zip")
if not ok then
    sys.alert('删除失败：'..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [获取图片对象某点颜色 (:get_color)](https://xxtouch.app/docs/handbook/image/imagem_get_color.md)
Path: handbook/image/imagem_get_color.md

# 获取图片对象某点颜色 (:get_color)


## 声明

```lua
颜色, 不透明度 = 图片:get_color(横坐标, 纵坐标)
```

## 参数

- 横坐标, 纵坐标
    整数型，需要获取颜色的点于当前图片对象上的坐标

## 返回值

- 颜色
    整数型，返回当前图片对象上的这个坐标的颜色值，值得一提的是，假如颜色不透明度不是 255，则该点颜色红绿蓝实际会需要考虑除以不透明率（不透明度/255）
- 不透明度
    整数型，返回当前图片对象上的这个坐标的不透明度，取值范围 0~255


## 说明

> 获取图片对象某点颜色，不同于屏幕取色之处在于，图片中的像素还多了透明度属性


## 示例

```lua
local img = image.load_file("/var/mobile/1.png")
local clr = img:get_color(100, 100)
sys.alert(string.format("图片上坐标 (100, 100) 的颜色为：0x%06x", clr))
```

---

Source: [递归修改文件所有者与权限 (sys.lchownmod_r)](https://xxtouch.app/docs/handbook/sys/sys.lchownmod_r.md)
Path: handbook/sys/sys.lchownmod_r.md

# 递归修改文件所有者与权限 (sys.lchownmod_r)


## 声明

```lua
sys.lchownmod_r(文件路径, 用户ID, 用户组ID, 权限)
```


## 参数

- 文件路径
    文本型
- 用户 ID
    整数型
- 用户组 ID
    整数型
- 权限
    整数型，权限值，例如八进制 `0755` 等价于 `7 * 8^2 | 5 * 8^1 | 5`
    文本型，权限值，例如 `"0755"` 或 `"rwxr-xr-x"`（自 20250625 版本起支持）


## 说明

> 将对目录下所有文件和子目录递归修改所有者与权限，不会遍历深层符号链接指向的目录
> 关键词：修复权限、修改权限、更改权限
> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
sys.lchownmod_r("/var/mobile/Media/1ferver", 501, 501, 7 * 8^2 | 5 * 8^1 | 5)

-- 20250625 以上版本支持以下两种形式参数
sys.lchownmod_r("/var/mobile/Media/1ferver", 501, 501, "0755")
sys.lchownmod_r("/var/mobile/Media/1ferver", 501, 501, "rwxr-xr-x")
```

---

Source: [获取当前设备的进程列表 (app.all_procs)](https://xxtouch.app/docs/handbook/app/app.all_procs.md)
Path: handbook/app/app.all_procs.md

# 获取当前设备的进程列表 (app.all_procs)


## 声明

```lua
进程信息数组 = app.all_procs()
```

## 返回值

- 进程信息数组
    顺序表型，返回进程列表

    <details>

    <summary>进程列表结构</summary>

    ```lua
    {
        {pid = 进程号1, name = 进程名1},
        {pid = 进程号2, name = 进程名2},
        ...
    }
    ```
    </details>

## 说明

> 该函数不保证能获取到进程名全名


## 示例

```lua
proc_list = app.all_procs()
```

---

Source: [获取设备所有的接口 IP (device.ifaddrs)](https://xxtouch.app/docs/handbook/device/device.ifaddrs.md)
Path: handbook/device/device.ifaddrs.md

# 获取设备所有的接口 IP (device.ifaddrs)


## 声明

```lua
接口信息数组 = device.ifaddrs()
```


## 返回值

- 接口信息数组
    顺序表型 | nil，成功返回一个特定结构的表，失败返回 nil
    <details>

    <summary>所有接口的信息结构如下</summary>

    ```lua
    {
        {"接口名 1", "IP1"},
        {"接口名 2", "IP2"},
        ...
    }
    ```
    </details>


## 说明

> 获取设备所有的接口 IP


## 示例

```lua
-- 获取设备的 WiFi IP
local ip = "没开 WiFi"
for i,v in ipairs(device.ifaddrs()) do
    if (v[1]=="en0") then
        ip = v[2]
    end
end
sys.alert(ip)
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [移动文件或目录 (file.move)](https://xxtouch.app/docs/handbook/file/file.move.md)
Path: handbook/file/file.move.md

# 移动文件或目录 (file.move)


## 声明

```lua
操作成败, 错误信息 = file.move(源路径, 目标路径 [, 模式])
```


## 参数

- 源路径
    文本型，源文件或目录的绝对路径
- 目标路径
    文本型，移动后的文件或目录的完整绝对路径，包含目标文件名或目录名
- 模式 20250914+
    文本型，可选参数，移动模式。取值：
    - 空字符串或省略：默认模式（no-clobber），当目标已存在时返回失败
    - "overwrite" 或 "o"：覆盖模式，直接替换已存在的目标（已存在的目标会被删除）
    - "merge" 或 "m"：合并模式（仅用于目录），保留目标中已存在的文件
    - "overwrite-merge" 或 "om"/"mo"：覆盖合并模式，合并目录但覆盖同名文件

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将 `源路径` 指向的文件或目录移动为 `目标路径`；在同一目录下更名即为重命名
> **该函数是“移动为”语义，不是“移动进”语义**。`目标路径` 指定最终的文件或目录，不会自动追加源文件名或目录名；即使目标已存在且为目录，或者目标路径以 `/` 结尾，也不会将源文件或目录放入该目录中
> 例如，要把 `/a/b/c` 移动到 `/d/e/` 中并保留名称 `c`，目标路径应写为 `/d/e/c`，不能只写 `/d/e/`
> 目标已存在时，按 `模式` 参数处理：默认模式返回失败，覆盖模式替换目标本身，目录合并模式则将源目录内容合并到目标目录
> 关键词：重命名文件、重命名目录、重命名文件夹、移动文件、移动目录、移动文件夹
> **该函数在 20250313 以后的版本方可使用**


## 示例

```lua
ok, err = file.move(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
    sys.alert('移动失败：'..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

### 移动到另一个目录并保留名称

```lua
-- 假设 /d/e 是已存在的目录，/d/e/c 尚不存在
file.move('/a/b/c', '/d/e/c') -- 正确：将 c 移动为 /d/e/c

-- 以下为独立的错误写法示例，目标是 e 本身，不是 e 目录中的 c
-- file.move('/a/b/c', '/d/e/') -- 默认模式下因目标已存在而失败

-- 覆盖模式会替换 e 本身，不会生成 /d/e/c（20250914+）
-- file.move('/a/b/c', '/d/e/', 'overwrite')
```

### 封装“移动进目录”函数

以下为自定义封装示例，需要 20250914 以后的版本。目标目录须已存在，函数会保留源文件或目录名，并将可选的 `mode` 参数传给 `file.move`。发生同名冲突时，仍按指定模式处理。

```lua
local function file_move_into(src_path, dst_dir, mode)
    if file.exists(dst_dir) ~= "directory" then
        return false, "Target is not a directory"
    end

    local name, err = file.path.last_component(src_path)
    if not name then
        return false, err
    end
    -- 避免将目标目录本身或其父目录作为最终目标。
    if name == "" or name == "/" or name == "." or name == ".." then
        return false, "Source path must end with a file or directory name"
    end

    local dst_path, path_err = file.path.add_component(dst_dir, name)
    if not dst_path then
        return false, path_err
    end
    return file.move(src_path, dst_path, mode)
end

-- 假设 /d/e 是已存在的目录，将 c 移动为 /d/e/c
local ok, err = file_move_into("/a/b/c", "/d/e/")
if not ok then
    print("移动失败："..err)
end

-- 如需替换 /d/e/c，可在调用时指定覆盖模式：
-- file_move_into("/a/b/c", "/d/e/", "overwrite")
```

**注**：上述代码使用了 [`file.exists`](/docs/handbook/file/file.exists.md)、[`file.path.last_component`](/docs/handbook/file/file.path.last_component.md) 和 [`file.path.add_component`](/docs/handbook/file/file.path.add_component.md)。

---

Source: [设置图片对象某点颜色 (:set_color)](https://xxtouch.app/docs/handbook/image/imagem_set_color.md)
Path: handbook/image/imagem_set_color.md

# 设置图片对象某点颜色 (:set_color)


## 声明

```lua
图像 = 图像:set_color(横坐标, 纵坐标, 颜色)
```


## 参数

- 横坐标, 纵坐标
    整数型，需要设置颜色的点于当前图片对象上的坐标
- 颜色
    整数型，需要设置的颜色值

## 返回值

- 图像
    图片对象，设置色后返回图片对象本体

## 说明

> 设置图片对象某点颜色
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝

---

Source: [递归创建目录 (sys.mkdir_p)](https://xxtouch.app/docs/handbook/sys/sys.mkdir_p.md)
Path: handbook/sys/sys.mkdir_p.md

# 递归创建目录 (sys.mkdir_p)


## 声明

```lua
sys.mkdir_p(目录路径)
```


## 参数

- 目录路径
    文本型

## 说明

> 递归创建目录；新建目录的所有者 UID/GID 为 501、权限为 八进制 0777
> 关键词：新建文件夹、创建文件夹
> **该函数在 20250220 以后版本方可使用**


## 示例

```lua
sys.mkdir_p("/var/mobile/Media/1ferver/lua/scripts/a/b/c/d")
```

---

Source: [设置 App 的 TCC 权限 (app.set_tcc)](https://xxtouch.app/docs/handbook/app/app.set_tcc.md)
Path: handbook/app/app.set_tcc.md

# 设置 App 的 TCC 权限 (app.set_tcc)

## 声明

```lua
操作成败, 原状态值 = app.set_tcc(应用包标识符, 服务标识, 状态值)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
- 服务标识
    文本型
    <details>

    <summary>TCC 服务标识列表</summary>

    ```lua
    kTCCServiceAccessibility
    kTCCServiceAddressBook
    kTCCServiceAppleEvents
    kTCCServiceCalendar
    kTCCServiceCamera
    kTCCServiceContactsFull
    kTCCServiceContactsLimited
    kTCCServiceDeveloperTool
    kTCCServiceFacebook
    kTCCServiceLinkedIn
    kTCCServiceListenEvent
    kTCCServiceLiverpool
    kTCCServiceLocation
    kTCCServiceMediaLibrary
    kTCCServiceMicrophone
    kTCCServiceMotion
    kTCCServicePhotos
    kTCCServicePhotosAdd
    kTCCServicePostEvent
    kTCCServiceReminders
    kTCCServiceScreenCapture
    kTCCServiceShareKit
    kTCCServiceSinaWeibo
    kTCCServiceSiri
    kTCCServiceSpeechRecognition
    kTCCServiceSystemPolicyAllFiles
    kTCCServiceSystemPolicyDesktopFolder
    kTCCServiceSystemPolicyDeveloperFiles
    kTCCServiceSystemPolicyDocumentsFolder
    kTCCServiceSystemPolicyDownloadsFolder
    kTCCServiceSystemPolicyNetworkVolumes
    kTCCServiceSystemPolicyRemovableVolumes
    kTCCServiceSystemPolicySysAdminFiles
    kTCCServiceTencentWeibo
    kTCCServiceTwitter
    kTCCServiceUbiquity
    kTCCServiceWillow
    kTCCServicePasteboard
    kTCCServiceUserTracking
    ```
    </details>
- 状态值
    整数型，设置 `状态值` 为 `-1` 删除 `应用程序包名` 这个应用的 TCC 权限

## 返回值

- 操作成败
    布尔值
- 原状态值
    整数型，返回 -1 时表示 App 原来没有这项权限


## 说明

> **软件版本在 1.3.8 或以上方可使用**


## 示例

```lua
app.set_tcc("com.apple.SafariViewService", "kTCCServicePasteboard", 2)
```

---

Source: [获取当前设备电池剩余电量 (device.battery_level)](https://xxtouch.app/docs/handbook/device/device.battery_level.md)
Path: handbook/device/device.battery_level.md

# 获取当前设备电池剩余电量 (device.battery_level)


## 声明

```lua
电量 = device.battery_level()
```

## 返回值

- 电量
    实数型，当前设备电池剩余电量，范围 0.0~1.0


## 示例

```lua
sys.alert("当前设备电池剩余电量："..(device.battery_level() * 100).."%")
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [拷贝文件或目录 (file.copy)](https://xxtouch.app/docs/handbook/file/file.copy.md)
Path: handbook/file/file.copy.md

# 拷贝文件或目录 (file.copy)


## 声明

```lua
操作成败, 错误信息 = file.copy(源路径, 目标路径 [, 模式])
```


## 参数

- 源路径
    文本型，源文件或目录的绝对路径
- 目标路径
    文本型，拷贝后的文件或目录的完整绝对路径，包含目标文件名或目录名
- 模式 20250914+
    文本型，可选参数，复制模式。取值：
    - 空字符串或省略：默认模式（no-clobber），当目标已存在时返回失败
    - "overwrite" 或 "o"：覆盖模式，直接替换已存在的目标（已存在的目标会被删除）
    - "merge" 或 "m"：合并模式（仅用于目录），保留目标中已存在的文件
    - "overwrite-merge" 或 "om"/"mo"：覆盖合并模式，合并目录但覆盖同名文件

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将 `源路径` 指向的文件或目录拷贝为 `目标路径`
> **该函数是“拷贝为”语义，不是“拷贝进”语义**。`目标路径` 指定最终的文件或目录，不会自动追加源文件名或目录名；即使目标已存在且为目录，或者目标路径以 `/` 结尾，也不会将源文件或目录放入该目录中
> 例如，要把 `/a/b/c` 拷贝到 `/d/e/` 中并保留名称 `c`，目标路径应写为 `/d/e/c`，不能只写 `/d/e/`
> 目标已存在时，按 `模式` 参数处理：默认模式返回失败，覆盖模式替换目标本身，目录合并模式则将源目录内容合并到目标目录
> 关键词：复制文件、拷贝文件、复制目录、拷贝目录、复制文件夹、拷贝文件夹
> **该函数在 20250313 以后的版本方可使用**


## 示例

```lua
ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
    sys.alert('拷贝失败：'..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

### 拷贝到另一个目录并保留名称

```lua
-- 假设 /d/e 是已存在的目录，/d/e/c 尚不存在
file.copy('/a/b/c', '/d/e/c') -- 正确：将 c 拷贝为 /d/e/c

-- 错误写法：目标是 e 本身，不是 e 目录中的 c
file.copy('/a/b/c', '/d/e/') -- 默认模式下因目标已存在而失败

-- 覆盖模式会替换 e 本身，不会生成 /d/e/c（20250914+）
-- file.copy('/a/b/c', '/d/e/', 'overwrite')
```

### 封装“拷贝进目录”函数

以下为自定义封装示例，需要 20250914 以后的版本。目标目录须已存在，函数会保留源文件或目录名，并将可选的 `mode` 参数传给 `file.copy`。发生同名冲突时，仍按指定模式处理。

```lua
local function file_copy_into(src_path, dst_dir, mode)
    if file.exists(dst_dir) ~= "directory" then
        return false, "Target is not a directory"
    end

    local name, err = file.path.last_component(src_path)
    if not name then
        return false, err
    end
    -- 避免将目标目录本身或其父目录作为最终目标。
    if name == "" or name == "/" or name == "." or name == ".." then
        return false, "Source path must end with a file or directory name"
    end

    local dst_path, path_err = file.path.add_component(dst_dir, name)
    if not dst_path then
        return false, path_err
    end
    return file.copy(src_path, dst_path, mode)
end

-- 假设 /d/e 是已存在的目录，将 c 拷贝为 /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
    print("拷贝失败："..err)
end

-- 如需替换 /d/e/c，可在调用时指定覆盖模式：
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")
```

**注**：上述代码使用了 [`file.exists`](/docs/handbook/file/file.exists.md)、[`file.path.last_component`](/docs/handbook/file/file.path.last_component.md) 和 [`file.path.add_component`](/docs/handbook/file/file.path.add_component.md)。

---

Source: [颜色替换 (:replace_color)](https://xxtouch.app/docs/handbook/image/imagem_replace_color.md)
Path: handbook/image/imagem_replace_color.md

# 颜色替换 (:replace_color)


## 声明

```lua
图片 = 图片:replace_color(原色, 替换色[, 原色相似度])
```


## 参数

- 原色
    整数型，原来的颜色
- 替换色
    整数型，需要变成的颜色
- 原色相似度
    整数型，可选参数，颜色相似度，范围 0~100，默认 100

## 返回值

- 图片
    图片对象，替换色后返回图片对象本体

## 说明

> 将图片对象上某种颜色 (或其近似色) 替换为另外的颜色
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝


## 示例

参考 [`utils.qr_encode` 中"替换二维码背景色"的示例](/docs/handbook/utils/utils.qr_encode.md)

---

Source: [创建一个执行任务 (sys.task)](https://xxtouch.app/docs/handbook/sys/sys.task.md)
Path: handbook/sys/sys.task.md

# 创建一个执行任务 (sys.task)


## 声明

```lua
任务 = sys.task(可执行文件路径 [, 参数...])
```

## 参数

- 可执行文件路径
    文本型
- 参数...
    文本型，可选不定参数，默认没有

## 返回值

- 任务
    执行任务对象，返回一个控制任务或执行任务的对象


## 任务对象方法列表

|方法|参数|返回值|说明|
|----|----|----|----|
|:launch\(\)|||启动任务，异步运行|
|:wait_until_exit\(\)|||同步等待任务结束，任务结束前会阻塞所有线程。|
|:set_stdin\(输入流\)|管道 \| 文本型||设置任务的输入流。参数可以是 `"std"`、`"/dev/null"`、文件路径、管道对象。任务启动后再调用将抛出错误|
|:stdin\(\)||管道 \| 文本型|获取任务的输入流。可能返回 `"std"`、`"/dev/null"`、文件路径、管道对象|
|:set_stdout\(输出流\)|管道 \| 文本型||设置任务的输出流。参数可以是 `"std"`、`"/dev/null"`、文件路径、管道对象。任务启动后再调用将抛出错误|
|:stdout\(\)||管道 \| 文本型|获取任务的输出流。可能返回 `"std"`、`"/dev/null"`、文件路径、管道对象|
|:set_stderr\(错误流\)|管道 \| 文本型||设置任务的错误流。参数可以是 `"std"`、`"/dev/null"`、文件路径、管道对象。任务启动后再调用将抛出错误|
|:stderr\(\)||管道 \| 文本型|获取任务的错误流。可能返回 `"std"`、`"/dev/null"`、文件路径、管道对象|
|:set_work_dir\(目录\)|文本型||设置任务的工作目录。任务启动后再调用将抛出错误|
|:work_dir\(\)||文本型|获取任务的工作目录|
|:set_env\(环境变量\)|表型||设置任务的环境变量键值词典。任务启动后再调用将抛出错误|
|:env\(\)||表型|获取任务的环境变量键值词典|
|:pid\(\)||整数型|获取任务的进程号，任务启动前获取返回 0|
|:is_running\(\)||布尔型|判断任务是否正在运行。即使 `:is_running()` 返回 false，也应当对任务调用一次 `:wait_until_exit()` 以阻止产生僵尸进程|
|:interrupt\(\)||布尔型|向任务主进程发送终止 SIGINT 信号|
|:terminate\(\)||布尔型|向任务主进程发送终止 SIGTERM 信号|
|:kill\(\)||布尔型|向任务所有进程发送强杀 SIGKILL 信号，任务对象被回收时会自动执行 kill 操作|
|:termination_status\(\)||整数型|获取任务的终止状态，如果任务尚未结束则返回 nil, 错误信息|
|:termination_reason\(\)||文本型|获取任务的终止原因，如果任务尚未结束则返回 nil, 错误信息|


## 管道对象方法列表

|方法|参数|返回值|说明|
|----|----|----|----|
|:read\(\)||字符串型|从管道中读取已经准备好的数据|
|:write\(数据\)|字符串型||向管道中写入数据|
|:wclose\(\)||布尔型, nil \| 文本型|关闭管道写端，成功返回 `true`，失败返回 `false, 错误信息`|
|:rclose\(\)||布尔型, nil \| 文本型|关闭管道读端，成功返回 `true`，失败返回 `false, 错误信息`|


## 说明

> 创建一个执行任务，返回一个执行任务对象
> 若不希望阻塞所有线程等待任务完成，可循环调用任务对象的 `:is_running()` 判断任务是否仍在运行；待其结束后，再调用一次 `:wait_until_exit()` 以确认任务已终止
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
-- 模拟以下 Shell 命令
-- echo "你好世界" | /usr/bin/gzip -fc | /usr/bin/gzip -dfc

local comp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-fc')    -- 创建压缩任务
local decomp_tsk = sys.task(jbroot('/usr/bin/gzip'), '-dfc') -- 创建解压任务

decomp_tsk:set_stdin(comp_tsk:stdout()) -- 设置解压任务的输入流为压缩任务的输出流

decomp_tsk:launch() -- 启动解压任务
comp_tsk:launch() -- 启动压缩任务

comp_tsk:stdin():write("你好世界") -- 向压缩任务的输入流写入数据
comp_tsk:stdin():wclose() -- 关闭压缩任务的输入流写端，表示输入流已经结束

comp_tsk:wait_until_exit() -- 等待压缩任务结束
decomp_tsk:wait_until_exit() -- 等待解压任务结束

nLog(decomp_tsk:stdout():read()) -- 读取解压任务的输出流，输出 "你好世界"
```

## 示例（调用巨魔持久助手刷新）

```lua
local persistence_helper_path = app.bundle_path('com.apple.tips')
if not persistence_helper_path then
    nLog('没有检测到 Tips.app，请先从 AppStore 安装 Tips（提示）应用')
    return
end
local root_helper_path = persistence_helper_path..'/trollstorehelper'
if file.exists(root_helper_path) ~= 'file' then
    nLog('未注入巨魔持久助手到 Tips，请先从 TrollStore -> Settings -> Install Persistence Helper 选择 Tips 注入')
    return
end
local tsk = sys.task(root_helper_path, 'refresh')
tsk:launch()
tsk:wait_until_exit()
sys.killall(9, 'SpringBoard', 'backboardd')
```

## 示例（调用巨魔安装卸载 App，重建图标缓存）

```lua
local function _trollstorehelper(...)
    local troll_path = app.bundle_path('com.opa334.TrollStore')
    assert(type(troll_path) == 'string', 'TrollStore needs to be installed.')
    local tsk = sys.task(troll_path..'/trollstorehelper', ...)
    tsk:set_stdin('/dev/null')
    tsk:launch()
    local outbuf = {}
    local errbuf = {}
    local function drain_stream(stream, buf)
        local data = stream:read('nb')
        if data and #data > 0 then
            buf[#buf + 1] = data
        end
    end
    while tsk:is_running() do
        drain_stream(tsk:stdout(), outbuf)
        drain_stream(tsk:stderr(), errbuf)
        sys.msleep(100)
    end
    tsk:wait_until_exit()
    drain_stream(tsk:stdout(), outbuf)
    drain_stream(tsk:stderr(), errbuf)
    if tsk:termination_status() == 0 then
        local ret = table.concat(outbuf)
        return ret
    else
        local ret = table.concat(errbuf)
        return nil, ret
    end
end

--- 使用 TrollStore 安装一个 App
---@param ipapath string 安装包路径
---@return string? 安装结果文本，失败返回 nil
---@return string? 错误信息，成功返回 nil
function troll_install(ipapath)
    return _trollstorehelper('install', ipapath)
end

--- 卸载 TrollStore 安装的 App
---@param bid string 应用包标识符
---@return string? 卸载结果文本，失败返回 nil
---@return string? 错误信息，成功返回 nil
function troll_uninstall(bid)
    return _trollstorehelper('uninstall', bid)
end

--- TrollStore 重建图标缓存，会需要消耗一些时间
---@return string? 重建结果文本，失败返回 nil
---@return string? 错误信息，成功返回 nil
function troll_rebuild_icon_cache()
    return _trollstorehelper('refresh-all')
end

-- 示例调用
nLog(troll_install(XXT_SCRIPTS_PATH..'/TrollDecrypt.tipa')) -- 安装 TrollDecrypt
nLog(troll_uninstall('com.fiore.trolldecrypt')) -- 卸载 TrollDecrypt
nLog(troll_rebuild_icon_cache()) -- 重建图标缓存
```

---

Source: [获取 App 打开的文件 (app.lsof)](https://xxtouch.app/docs/handbook/app/app.lsof.md)
Path: handbook/app/app.lsof.md

# 获取 App 打开的文件 (app.lsof)

## 声明

```lua
文件列表, 错误信息 = app.lsof(应用包标识符 或 进程号)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看
- 进程号
    整数型，需要查看的应用的进程号

## 返回值

- 文件列表
    表型 | nil
    <details>
    <summary>成功返回一个特定结构的表，失败返回 nil</summary>

    ```lua
    {
        opensockets = {
            {
                fd = integer_value,
                kind = "TCP" | "IN",
                ["local"] = {
                    address = string_value,
                    port = integer_value,
                },
                ["remote"] = {
                    address = string_value,
                    port = integer_value,
                },
            },
            ...
        },
        openfiles = {
            {
                fd = integer_value,
                path = string_value,
            },
            ...
        },
    }
    ```
    </details>

- 错误信息
    文本型 或 nil，失败则返回错误信息


## 说明

> 列出指定 App 打开的文件描述符及 socket 描述符
> **软件版本在 1.3.8 或以上方可使用**


## 示例

```lua
nLog(app.lsof('com.apple.Preferences'))
```

---

Source: [获取当前设备充电状态 (device.battery_state)](https://xxtouch.app/docs/handbook/device/device.battery_state.md)
Path: handbook/device/device.battery_state.md

# 获取当前设备充电状态 (device.battery_state)


## 声明

```lua
充电状态 = device.battery_state()
```


## 返回值

- 充电状态
    文本型，取值如下：
    `"Full"`　已连接电源且电量已充满
    `"Charging"`　已连接电源并正在充电
    `"Unplugged"`　未连接电源
    `"Unknown"`　未知状态


## 示例

```lua
状态表 = {
    Full = "连接并已充满",
    Charging = "连接并在充电",
    Unplugged = "没插电源",
    Unknown = "未知状态",
}
--
sys.alert("当前设备电池充电状态："..状态表[device.battery_state()])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [从 16 进制文本转回 (string.from_hex)](https://xxtouch.app/docs/handbook/ext-string/string.from_hex.md)
Path: handbook/ext-string/string.from_hex.md

# 从 16 进制文本转回 (string.from_hex)


## 声明

```lua
数据内容 = string.from_hex(16进制文本)
```


## 参数

- 16 进制文本
    文本型，需要转换成字符串的 16 进制文本

## 返回值

- 数据内容
    字符串型 或 nil，返回字符串，如果输入参数不是 16 进制文本，则返回 nil


## 说明

> `string.to_hex` 的反函数；将 16 进制文本转回字符串（或二进制数据块）


## 示例

```lua
sys.alert(string.from_hex('e4b880e4ba9be695b0e68dae'))
-- 输出 "一些数据"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [查找文件或目录 (file.find)](https://xxtouch.app/docs/handbook/file/file.find.md)
Path: handbook/file/file.find.md

# 查找文件或目录 (file.find)


## 声明

```lua
文件列表 = file.find(匹配模式)
```


## 参数

- 匹配模式
    表型 | 文本型

## 返回值

- 文件列表
    表型，返回找到的文件名列表


## 说明

> 使用通配符模式或 Lua 精确匹配搜索文件或目录，返回匹配的文件名列表。
> 如果 `匹配模式` 是字符串，则使用通配符模式匹配，通配符模式匹配仅支持 \*、?、\[\.\.\.\] 这三种通配符。
> 如果 `匹配模式` 是表，则使用 Lua 精确匹配。
> **该函数在 20250416 以后的版本方可使用**


## 示例

### 简单通配符模式

```lua
-- 简单通配符模式，仅支持 * ? [...] 三种基本通配符
-- * 表示匹配任意长度任意字符（长度也可以是 0）
-- ? 表示匹配单个任意字符
-- [...]  表示匹配单个中括号里的任意字符，例如 [abc]haha.txt 表示 ahaha.txt bhaha.txt chaha.txt 都匹配
-- [!...] 表示匹配单个非中括号里的任意字符，例如 [!abc]haha.txt 表示 ahaha.txt bhaha.txt chaha.txt 不匹配，其它单个字符例如 xhaha.txt 才能匹配
local results = file.find("/private/var/mobile/Containers/Shared/AppGroup/*/Library/Preferences/*.plist")
```

### 精确通配模式

```lua
-- 精确 Lua 模式匹配模式
-- 精确匹配使用 Lua 表分段构造匹配模式，字符串为字面量判断，模式匹配可以使用返回真假的函数来决定当前分段是否有效
local results = file.find{ --<--- 注意这里是大括号
    "/private/var/mobile/Containers/Shared/AppGroup/", -- 普通字符串不需要模式匹配
    function(s) return s:match("^[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+$") end, -- 使用函数匹配当前分段
    "/Library/Preferences/",
    function(s) return s:match("%.plist$") end, -- 使用函数匹配当前分段
}
-- 精确 Lua 模式匹配模式也可使用大括号包裹单个字符串以构造一个简易模式匹配函数
local results = file.find{ --<--- 注意这里是大括号
    "/private/var/mobile/Containers/Shared/AppGroup/", -- 普通字符串不需要模式匹配
    {"^[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+%-[A-F0-9]+$"}, -- 使用表包裹单个字符串表示这是一个需要使用模式匹配的分段
    "/Library/Preferences/", -- 普通字符串不需要模式匹配
    {"%.plist$"}, -- 使用表包裹单个字符串表示这是一个需要使用模式匹配的分段
}
```

---

Source: [图中贴图 (:draw_image)](https://xxtouch.app/docs/handbook/image/imagem_draw_image.md)
Path: handbook/image/imagem_draw_image.md

# 图中贴图 (:draw_image)


## 声明

```lua
大图像 = 大图像:draw_image(小图像[, {
   left = 左上的 x 坐标,
   top = 左上的 y 坐标,
   alpha = 不透明度,
   background = {
      {颜色*, 色偏*},
      {颜色*, 色偏*},
      ...
   },
}])
```


## 参数

- 小图像
    图片对象，需要绘制到 大图像 上的图像
- 左上的 x 坐标
    整数型，可选参数，需要将 小图像 绘制到 大图像 的左上角的 x 坐标，默认 0
- 左上的 y 坐标
    整数型，可选参数，需要将 小图像 绘制到 大图像 的左上角的 y 坐标，默认 0
- 不透明度
    整数型，可选参数，小图像 的不透明度，范围 0~255，默认 255
- 颜色\*, 色偏\*
    顺序表型，可选参数，小图像 上的与 颜色\* 色差在 色偏\* 范围内的颜色将不会绘制到 大图像 上，默认 不忽略任何颜色

## 返回值

- 大图像
    图片对象，返回大图像本体


## 说明

> 在图像上绘制另外一个图像
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝

---

Source: [问系统一个问题 (sys.mgcopyanswer)](https://xxtouch.app/docs/handbook/sys/sys.mgcopyanswer.md)
Path: handbook/sys/sys.mgcopyanswer.md

# 问系统一个问题 (sys.mgcopyanswer)


## 声明

```lua
答案 = sys.mgcopyanswer(问题)
```


## 参数

- 问题
    文本型，问题名字，一些 问题名字 参考 [MobileGestalt.h](https://github.com/Cykey/ios-reversed-headers/blob/master/MobileGestalt/MobileGestalt.h)

## 返回值

- 答案
    字符串型 或 表型 或 实数型 或 整数型 或 布尔型 或 nil，系统的回复，如果问题不被支持，则返回 nil


## 说明

> 获取一些系统信息，底层使用 [MGCopyAnswer](https://iphonedevwiki.net/index.php/LibMobileGestalt.dylib) 完成
> 关键词：获取系统信息、读取设备信息、设备标识、读取手机号


## 示例

```lua
sys.alert("设备的序列号是："..sys.mgcopyanswer("SerialNumber"))
sys.alert("设备的 IMEI 是："..sys.mgcopyanswer("InternationalMobileEquipmentIdentity"))
sys.alert("设备的 MEID 是："..sys.mgcopyanswer("MobileEquipmentIdentifier"))
sys.alert(string.format('设备的 ECID 是：%016X', sys.mgcopyanswer('UniqueChipID')))

local infos = sys.mgcopyanswer('CarrierBundleInfoArray')
if type(infos) == 'table' and #infos > 0 then
    local info = infos[1]
    if type(info.InternationalMobileSubscriberIdentity) == 'string' then
        sys.alert("运营商 IMSI 是："..info.InternationalMobileSubscriberIdentity)
    else
        sys.alert("无法读取运营商 IMSI，请确认设备已正确插入 SIM 卡")
    end
    if type(info.IntegratedCircuitCardIdentity) == 'string' then
        sys.alert("运营商 ICCID 是："..info.IntegratedCircuitCardIdentity)
    else
        sys.alert("无法读取运营商 ICCID，请确认设备已正确插入 SIM 卡")
    end
else
    sys.alert("无法读取运营商信息，请确认设备已正确插入 SIM 卡")
end

local phone_number = sys.mgcopyanswer('PhoneNumber')
if sys.mgcopyanswer('SIMTrayStatus') == 'kCTSIMSupportSIMTrayInsertedWithSIM' and type(phone_number) == 'string' then
    sys.alert("手机号是："..phone_number)
else
    sys.alert("无法读取手机号，请确认设备已正确插入 SIM 卡")
end
```

---

Source: [点击 UI 元素 (ui_element.click)](https://xxtouch.app/docs/handbook/ui_element/ui_element.click.md)
Path: handbook/ui_element/ui_element.click.md

# 点击 UI 元素 (ui_element.click)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.click(选择器或元素 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 用于点击按钮、列表项、键盘按键或其它可点击 UI。
> 坐标表中的坐标单位为物理像素。固定坐标点击请优先使用 [touch.tap](/docs/handbook/touch/touch.tap.md)。
> 匹配多个目标且无法判断唯一目标时可能返回 `nil, "ambiguous target"`。

## 示例

```lua
local ui_element = require("ui_element")

local ok, info_or_err = ui_element.click({
    title = "继续",
    role = "button",
})

if not ok then
    sys.toast(info_or_err)
end
```

**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [! 安装 IPA 安装包 (app.install)](https://xxtouch.app/docs/handbook/app/app.install.md)
Path: handbook/app/app.install.md

# ! 安装 IPA 安装包 (app.install)


## 声明

```lua
安装成败 = app.install(文件路径 [, 强行安装 ])
```


## 参数

- 文件路径
    文本型，需要安装的 App 安装包 (ipa 格式) 绝对路径
- 强行安装
    布尔型，可选参数，是否强行安装。true 表示无论版本高低都覆盖安装（可用于降级）；false 表示仅当待装 ipa 版本高于已装版本时才安装，版本相同或更低则跳过。默认为 false

## 返回值

- 安装成败
    布尔型，安装成功返回 true，安装失败返回 false


## 说明

> 后台安装一个 ipa 格式的安装包
> **安装完成前停止脚本，可能会导致半安装状态**
> 调用此函数前需确保在目标设备中已安装过 AppSync 插件


## 示例

```lua
app.install("/var/mobile/1.ipa", true) -- 强行覆盖安装，用于降级安装 App
--
if app.install("/var/mobile/1.ipa") then
    -- 安装成功
else
    -- 安装失败
end
```

---

Source: [打开设备 WiFi (device.turn_on_wifi)](https://xxtouch.app/docs/handbook/device/device.turn_on_wifi.md)
Path: handbook/device/device.turn_on_wifi.md

# 打开设备 WiFi (device.turn_on_wifi)


## 声明

```lua
device.turn_on_wifi()
```

## 示例

```lua
device.turn_on_wifi()
```

---

Source: [切换当前工作目录 (file.chdir)](https://xxtouch.app/docs/handbook/file/file.chdir.md)
Path: handbook/file/file.chdir.md

# 切换当前工作目录 (file.chdir)


## 声明

```lua
操作成败, 错误信息 = file.chdir(目录路径)
```


## 参数

- 目录路径
    文本型


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 切换当前工作目录，等同于 lfs.chdir
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local success, err = file.chdir("/var/mobile/Media/1ferver/lua/scripts/")
if success then
    sys.alert("切换成功")
else
    sys.alert("切换失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [二值化处理图片对象 (:binaryzation)](https://xxtouch.app/docs/handbook/image/imagem_binaryzation.md)
Path: handbook/image/imagem_binaryzation.md

# 二值化处理图片对象 (:binaryzation)


## 声明

```lua
图片 = 图片:binaryzation({
    [white_background = 白背景,]
    [csim_mode = 相似度模式,]
    [csim_algorithm = 颜色相似度算法,]
    {颜色*, 色偏*},
    {颜色*, 色偏*},
    ...
})
```
```lua
图片 = 图片:binaryzation("cx*-cox*,cx*-cox*...")
```


## 参数

- 白背景（自 20250302 版本起支持）
    布尔型，可选参数，是否将背景设置为白色，默认 false，即白前景黑背景
- 相似度模式（自 20250302 版本起支持）
    布尔型，可选参数，是否使用相似度模式；启用时 `色偏*` 表示相似度而非色差值，默认 false
- 颜色相似度算法（自 20250302 版本起支持）
    整数型，可选参数，颜色相似度算法，仅在相似度模式下生效，默认 0
    <details>

    <summary>颜色相似度算法</summary>

    ```lua
    0 为 XXT 默认算法，梯度陡峭，差值使相似度下降很快
    1 为曼哈顿算法，梯度平滑
    2 为欧几里得算法，梯度平滑
    ```
    </details>
- 颜色\*, 色偏\*
    整数型，颜色值白名单，颜色\* 是颜色值本身，色偏\* 是 颜色\* 的最大色差值
- cx\*-cox\*
    文本型，颜色值白名单，cx\* 是颜色值本身的 16 进制文本描述，cox\* 是 cx\* 的最大色差值 16 进制文本描述

## 返回值

- 图片
    图片对象，二值化后返回图片对象本体


## 说明

> 二值化处理图片对象
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝


## 示例

```lua
local pic = screen.image(462, 242, 569, 272)
pic = pic:binaryzation({
    {0x9D5D39, 0x0F1F26},
    {0xD3D3D2, 0x2C2C2D},
})
```

```lua
local pic = screen.image(462, 242, 569, 272)
pic = pic:binaryzation("9D5D39-0F1F26,D3D3D2-2C2C2D")
```

```lua
local pic = screen.image(462, 242, 569, 272)
pic = pic:binaryzation({
    csim_mode = true,        -- 使用相似度模式
    csim_algorithm = 2,      -- 使用欧几里得算法
    white_background = true, -- 将背景设置为白色
    {0x9D5D39, 90},          -- 颜色 0x9D5D39 的相似度为 90%
    {0xD3D3D2, 90},          -- 颜色 0xD3D3D2 的相似度为 90%
})
```

---

Source: [读取 sysctl 键值 (sys.ctlbyname)](https://xxtouch.app/docs/handbook/sys/sys.ctlbyname.md)
Path: handbook/sys/sys.ctlbyname.md

# 读取 sysctl 键值 (sys.ctlbyname)


## 声明

```lua
数据 = sys.ctlbyname(键名)
```


## 参数

- 键名
    文本型，sysctl 的完整键名，例如 `kern.boottime`、`hw.memsize`

## 返回值

- 数据
    字符串型，返回指定键的原始字节数据，无法读取时返回 `nil`


## 说明

> 调用底层 `sysctlbyname` 读取内核/硬件运行参数；返回的原始字节通常需要再解包
> 关键词：读取系统信息、获取 sysctl 参数、解析内核状态


## 示例

```lua
local raw = sys.ctlbyname('hw.machine')
if type(raw) == 'string' then
    nLog('设备类型: '..raw:gsub('%z+$', ''))
else
    nLog('无法读取 hw.machine')
end

local sec, usec = string.unpack('li', sys.ctlbyname('kern.boottime'))
nLog('已经开机秒', os.time() - sec)
```

---

Source: [滚动 UI 元素或当前页面 (ui_element.scroll)](https://xxtouch.app/docs/handbook/ui_element/ui_element.scroll.md)
Path: handbook/ui_element/ui_element.scroll.md

# 滚动 UI 元素或当前页面 (ui_element.scroll)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.scroll(方向 [, 选项 ])
状态, 信息或错误信息 = ui_element.scroll(选择器或元素, 方向 [, 选项 ])
```

## 参数

- 选择器或元素
    可选参数，表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 方向
    文本型，支持 `"down"`、`"up"`、`"left"`、`"right"`、`"top"`、`"bottom"`。
- 选项
    可选参数，表型。可使用 `point`、`x`、`y` 指定命中点，也可使用 `steps` 指定步进参数。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 不传选择器时，默认尝试滚动当前页面。
> 传入选择器时，会尝试滚动目标元素所在的可滚动区域。
> 如果需要确定滚动多页，建议在 Lua 脚本中循环调用并自行检查页面变化。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.scroll("down", {
    point = { x = 200, y = 700 },
})

ui_element.scroll({
    text_contains = "列表",
}, "up")
```

---

Source: [卸载一个应用 (app.uninstall)](https://xxtouch.app/docs/handbook/app/app.uninstall.md)
Path: handbook/app/app.uninstall.md

# 卸载一个应用 (app.uninstall)


## 声明

```lua
卸载成败 = app.uninstall(应用包标识符)
```


## 参数

- 应用包标识符
    文本型，如需要定位应用的应用包标识符，可于 **XXT 应用程序--更多--应用列表** 中查看

## 返回值

- 卸载成败
    布尔型，卸载成功返回 true，卸载失败返回 false


## 说明

> 后台卸载一个应用程序
> **卸载过程中停止脚本，可能会导致半卸载状态**


## 示例

```lua
if app.uninstall("com.tencent.mqq") then
    -- 卸载成功
else
    -- 卸载失败
end
```

---

Source: [关闭设备 WiFi (device.turn_off_wifi)](https://xxtouch.app/docs/handbook/device/device.turn_off_wifi.md)
Path: handbook/device/device.turn_off_wifi.md

# 关闭设备 WiFi (device.turn_off_wifi)


## 声明

```lua
device.turn_off_wifi()
```

## 示例

```lua
device.turn_off_wifi()
```

---

Source: [获取当前工作目录 (file.currentdir)](https://xxtouch.app/docs/handbook/file/file.currentdir.md)
Path: handbook/file/file.currentdir.md

# 获取当前工作目录 (file.currentdir)


## 声明

```lua
目录路径, 错误信息 = file.currentdir()
```


## 返回值

- 目录路径
    文本型，操作成功返回目录路径，操作失败返回 nil
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获取当前工作目录，等同于 lfs.currentdir
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local cwd, err = file.currentdir()
if cwd then
    sys.alert("当前工作目录："..cwd)
else
    sys.alert("获取当前工作目录失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [图片多点颜色匹配 (:is_colors)](https://xxtouch.app/docs/handbook/image/imagem_is_colors.md)
Path: handbook/image/imagem_is_colors.md

# 图片多点颜色匹配 (:is_colors)


## 声明

```lua
是否完全匹配 = 图像:is_colors(...)
```


## 返回值

- 是否完全匹配
    布尔型，返回是否完全匹配


## 说明

> 图片多点颜色匹配
> 参数与返回值与 [屏幕多点颜色匹配 (screen.is_colors)](/docs/handbook/screen/screen.is_colors.md) 一致

---

Source: [获取系统版本 (sys.version)](https://xxtouch.app/docs/handbook/sys/sys.version.md)
Path: handbook/sys/sys.version.md

# 获取系统版本 (sys.version)


## 声明

```lua
系统版本 = sys.version()
```


## 返回值

- 系统版本
    文本型，返回系统版本号


## 说明

> 该函数可在 XUI 中使用


## 示例

```lua
sys.alert('当前系统版本：'..sys.version())
```

---

Source: [追加输入文本 (ui_element.input_text)](https://xxtouch.app/docs/handbook/ui_element/ui_element.input_text.md)
Path: handbook/ui_element/ui_element.input_text.md

# 追加输入文本 (ui_element.input_text)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.input_text(选择器或元素, 文本 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 文本
    文本型，要追加输入的内容。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 该接口会先定位文本输入目标，再追加输入文本。
> 如果需要替换原有文本，使用 [`set_text`](ui_element.set_text.md)。

## 示例

```lua
local ui_element = require("ui_element")

local ok, info_or_err = ui_element.input_text({
    title = "搜索",
    role = "text_field",
}, "XXTouch")

if not ok then
    sys.toast(info_or_err)
end
```

**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [打开设备蜂窝数据 (device.turn_on_data)](https://xxtouch.app/docs/handbook/device/device.turn_on_data.md)
Path: handbook/device/device.turn_on_data.md

# 打开设备蜂窝数据 (device.turn_on_data)


## 声明

```lua
device.turn_on_data()
```

## 示例

```lua
device.turn_on_data()
```

---

Source: [获取文件属性 (file.attrs)](https://xxtouch.app/docs/handbook/file/file.attrs.md)
Path: handbook/file/file.attrs.md

# 获取文件属性 (file.attrs)


## 声明

```lua
属性表, 错误信息 = file.attrs(目录路径 [, 请求字段])
```


## 参数

- 目录路径
    文本型
- 请求字段
    可选参数，支持以下三种传法：
    - 省略：创建并返回包含所有字段的属性表
    - 传入一个表（表型）：不新建表，而是将属性填充到传入的表中
    - 传入单个字段名（文本型）：直接返回该字段的值
    - "dev"：这表示文件的 inode 所在的设备
    - "ino"：文件的 inode 号
    - "mode"：文件类型，可能是 "file", "directory", "link", "socket", "named pipe", "char device", "block device" 或 "other"
    - "nlink"：硬链接数
    - "uid"：文件所有者 ID
    - "gid"：文件所有者组 ID
    - "rdev"：特殊文件 inode 的设备类型
    - "access"：文件最近访问时间
    - "modification"：文件最近修改时间
    - "change"：文件状态最近改变时间
    - "size"：文件大小，单位为字节
    - "permissions"：文件权限
    - "blksize"：文件系统 I/O 的块大小
    - "blocks"：文件已分配的 512 字节块数


## 返回值

- 属性表
    表型，操作成功返回属性表，操作失败返回 nil
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获取文件属性；若目标是符号链接，返回的是链接指向的目标文件的属性，等同于 `lfs.attributes`
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local info, err = file.attrs("/var/mobile/Media/1ferver/lua/scripts/")
if info then
    sys.alert("文件信息："..json.encode(info))
else
    sys.alert("获取文件属性失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [图中找色 (:find_color)](https://xxtouch.app/docs/handbook/image/imagem_find_color.md)
Path: handbook/image/imagem_find_color.md

# 图中找色 (:find_color)

## 声明

```lua
横坐标, 纵坐标 = 图片:find_color({
    [find_all = 是否搜索多个结果,]
    [max_results = 最大结果数,]
    [max_miss = 允许最多未命中数,]
    [find_order = 找色顺序,]
    [csim_algorithm = 颜色相似度算法,]
    {起始点横坐标, 起始点纵坐标, 起始点颜色[, 起始点相似度]},
    {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
    {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
    ...
} [, 全局相似度, 左, 上, 右, 下 ])
```


## 参数

- 是否搜索多个结果
    布尔型，可选参数，这个标签设置为 true 会返回范围内所有匹配位置的一个表，格式为 \{\{x1, y1\}, \{x2, y2\}, ...\}，默认 false
- 最大结果数
    整数型，可选参数，当 find_all (是否搜索多个结果)  标签设置为 true 的时候，这个表示最多返回结果数，最多可以设为 1000，默认 100
- 允许最多未命中数
    整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算找到
- 找色顺序
    整数型，可选参数，代表找色顺序，取值范围 1~8，默认 1
    <details>

    <summary>找色顺序取值说明</summary>

    ```lua
    1 上下左右
    2 左右上下
    3 右左上下
    4 上下右左
    5 下上右左
    6 右左下上
    7 左右下上
    8 下上左右
    ```

    **屏幕找色函数 screen.find_color 没有这个字段**
    [找色顺序演示](https://github.com/havonz/XXTouchDebs/blob/master/%E8%84%9A%E6%9C%AC%E6%BA%90%E7%A0%81/%E6%89%BE%E8%89%B2%E6%96%B9%E5%90%91%E6%B5%8B%E8%AF%95.lua)
    </details>
- 颜色相似度算法（自 20250302 版本起支持）
    整数型，可选参数，颜色相似度算法，默认 0
    <details>

    <summary>颜色相似度算法</summary>

    ```lua
    0 为 XXT 默认算法，梯度陡峭，差值使相似度下降很快
    1 为曼哈顿算法，梯度平滑
    2 为欧几里得算法，梯度平滑
    ```
    </details>
- 起始点横坐标, 起始点纵坐标
    整数型，代表起始坐标，它并不是限制找色的范围为固定这一点，而仅仅是给偏移位置一个相对坐标。若不需要使用偏移，可填 0, 0
- 起始点颜色
    整数型，代表需要搜索的那一点的颜色
- 起始点相似度
    整数型，可选参数，需要搜索的那一点颜色的相似度，取值范围 1~100，默认 100
- 偏移点横坐标\*, 偏移点纵坐标\*
    整数型，代表一个偏移位置坐标
- 偏移点颜色\*
    整数型，代表偏移位置需要匹配的颜色
- 偏移点相似度\*
    整数型，可选参数，偏移位置的颜色的相似度，取值范围 -100~100，默认 100，负相似度意味着匹配小于该绝对值的相似度
- 全局相似度
    整数型，可选参数，如果没有给单个点设置相似度，那么每一点都会用这个相似度，取值范围 1~100，默认 100
- 左, 上, 右, 下
    整数型，可选参数，代表搜索区域，默认 全图


## 返回值

- 横坐标, 纵坐标
    整数型，返回匹配色的第一个色的坐标，搜索失败返回 -1, -1


## 说明

> 使用相似度模式查找，获取区域中第一个完全匹配的多点颜色结构的位置
> 偏色模式用法参考 [多点色偏模式找色 (screen.find_color)](/docs/handbook/screen/screen.find_color-co.md)


## 示例

```lua
图片 = screen.image()

x, y = 图片:find_color({
    {  0,   0, 0xec1c23},
    { 12,  -3, 0xffffff, 85},
    {  5, -18, 0x00adee},
    { -1, -10, 0xffc823},
    {  2, -34, 0xa78217},
    { 12, -55, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
--[[
    在图片左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90
    且它的相对坐标 (12, -3) 的位置的颜色与 0xffffff 相似度大于 85
    且它的相对坐标 (5, -18) 的位置的颜色与 0x00adee 相似度大于 90
    且…… (后面的同理) 都能匹配的那个点
--]]
--
-- 等效代码如下：
--
x, y = 图片:find_color({
    { 509, 488, 0xec1c23},
    { 521, 485, 0xffffff, 85},
    { 514, 470, 0x00adee},
    { 508, 478, 0xffc823},
    { 511, 454, 0xa78217},
    { 521, 433, 0xd0d2d2},
}, 90, 0, 0, 100, 100)
--
--[[
    在图片左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90
    且它的相对坐标 (521-509, 485-488) 的位置的颜色与 0xffffff 相似度大于 85
    且它的相对坐标 (514-509, 470-488) 的位置的颜色与 0x00adee 相似度大于 90
    且…… (后面的同理) 都能匹配的那个点
--]]
```

---

Source: [获取 CoreFoundation 版本 (sys.cfversion)](https://xxtouch.app/docs/handbook/sys/sys.cfversion.md)
Path: handbook/sys/sys.cfversion.md

# 获取 CoreFoundation 版本 (sys.cfversion)

## 声明

```lua
版本号 = sys.cfversion()
```


## 返回值

- 版本号
    实数型，获取当前设备上的 CoreFoundation 的版本，CoreFoundation 版本通常可以用来确定当前的 iOS 版本范围。参考 [CoreFoundationVersionNumber](https://github.com/theos/headers/blob/master/version.h)


## 说明

> **软件版本在 1.3.8 或以上方可使用**


## 示例

```lua
sys.alert('当前 CoreFoundation 版本：'..sys.cfversion())
```

---

Source: [设置文本内容 (ui_element.set_text)](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_text.md)
Path: handbook/ui_element/ui_element.set_text.md

# 设置文本内容 (ui_element.set_text)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.set_text(选择器或元素, 文本 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 文本
    文本型，要设置的内容。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 该接口用于把文本输入目标的内容替换为指定文本。
> 如果目标控件不支持直接设置文本，可能返回失败。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.set_text({
    title = "搜索",
    role = "text_field",
}, "XXTouch")
```

---

Source: [关闭设备蜂窝数据 (device.turn_off_data)](https://xxtouch.app/docs/handbook/device/device.turn_off_data.md)
Path: handbook/device/device.turn_off_data.md

# 关闭设备蜂窝数据 (device.turn_off_data)


## 声明

```lua
device.turn_off_data()
```

## 示例

```lua
device.turn_off_data()
```

---

Source: [获取符号链接属性 (file.lattrs)](https://xxtouch.app/docs/handbook/file/file.lattrs.md)
Path: handbook/file/file.lattrs.md

# 获取符号链接属性 (file.lattrs)


## 声明

```lua
属性表, 错误信息 = file.lattrs(目录路径 [, 请求字段])
```


## 参数

- 目录路径
    文本型
- 请求字段
    可选参数，支持以下三种传法：
    - 省略：创建并返回包含所有字段的属性表
    - 传入一个表（表型）：不新建表，而是将属性填充到传入的表中
    - 传入单个字段名（文本型）：直接返回该字段的值
    - "dev"：这表示文件的 inode 所在的设备
    - "ino"：文件的 inode 号
    - "mode"：文件类型，可能是 "file", "directory", "link", "socket", "named pipe", "char device", "block device" 或 "other"
    - "nlink"：硬链接数
    - "uid"：文件所有者 ID
    - "gid"：文件所有者组 ID
    - "rdev"：特殊文件 inode 的设备类型
    - "access"：文件最近访问时间
    - "modification"：文件最近修改时间
    - "change"：文件状态最近改变时间
    - "size"：文件大小，单位为字节
    - "permissions"：文件权限
    - "blksize"：文件系统 I/O 的块大小
    - "blocks"：文件已分配的 512 字节块数
    - "target"：符号链接指向的文件路径


## 返回值

- 属性表
    表型，操作成功返回属性表，操作失败返回 nil
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 获取文件属性；若目标是符号链接，返回符号链接本身的信息（而不是指向的目标），等同于 `lfs.symlinkattributes`
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local info, err = file.lattrs("/var/mobile/Media/1ferver/lua/scripts/")
if info then
    sys.alert("文件信息："..json.encode(info))
else
    sys.alert("获取文件属性失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [图中找图 (:find_image)](https://xxtouch.app/docs/handbook/image/imagem_find_image.md)
Path: handbook/image/imagem_find_image.md

# 图中找图 (:find_image)


## 声明

```lua
横坐标, 纵坐标 = 大图:find_image(小图片 [, 可信度, 左, 上, 右, 下 ])
查找结果 = 大图:find_image(小图片 [, 选项, 左, 上, 右, 下 ])
```


## 参数

- 小图片
    图片对象，需要找的小图


## 返回值

- 横坐标, 纵坐标
    整数型，找到的小图在大图上的最匹配的位置的左上角坐标


## 说明

> 在图上找小图片，参数和返回值与 [屏幕找图 (screen.find_image)](/docs/handbook/screen/screen.find_image.md) 一致
> **软件版本在 1.3.8 以上可使用**

---

Source: [获取 XXTouch 版本 (sys.xtversion)](https://xxtouch.app/docs/handbook/sys/sys.xtversion.md)
Path: handbook/sys/sys.xtversion.md

# 获取 XXTouch 版本 (sys.xtversion)


## 声明

```lua
版本号 = sys.xtversion()
```


## 返回值

- 版本号
    文本型，返回 XXTouch 版本号


## 说明

> 该函数可在 XUI 中使用


## 示例

```lua
sys.alert('当前 XXTouch 版本：'..sys.xtversion())
```

---

Source: [清空文本内容 (ui_element.clear_text)](https://xxtouch.app/docs/handbook/ui_element/ui_element.clear_text.md)
Path: handbook/ui_element/ui_element.clear_text.md

# 清空文本内容 (ui_element.clear_text)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.clear_text(选择器或元素 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 该接口用于清空文本输入目标。
> 个别控件是否接受清空取决于目标 App 当前界面。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.clear_text({
    title = "搜索",
    role = "text_field",
})
```

---

Source: [打开设备蓝牙 (device.turn_on_bluetooth)](https://xxtouch.app/docs/handbook/device/device.turn_on_bluetooth.md)
Path: handbook/device/device.turn_on_bluetooth.md

# 打开设备蓝牙 (device.turn_on_bluetooth)


## 声明

```lua
device.turn_on_bluetooth()
```

## 示例

```lua
device.turn_on_bluetooth()
```

---

Source: [创建文件链接 (file.link)](https://xxtouch.app/docs/handbook/file/file.link.md)
Path: handbook/file/file.link.md

# 创建文件链接 (file.link)


## 声明

```lua
操作成败, 错误信息 = file.link(源文件路径, 目标文件路径 [, 符号链接])
```


## 参数

- 源文件路径
    文本型
- 目标文件路径
    文本型
- 符号链接
    布尔型，可选参数，如果为 true，则创建符号链接，否则创建硬链接


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 创建文件链接，等同于 lfs.link
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local info, err = file.link(jbroot("/var/mobile/Media/1ferver"), "/var/mobile/Media/1ferver", true)
if info then
    sys.alert("创建符号链接成功")
else
    sys.alert("创建符号链接失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [! 图片文字识别 (:ocr_text)](https://xxtouch.app/docs/handbook/image/imagem_ocr_text.md)
Path: handbook/image/imagem_ocr_text.md

# ! 图片文字识别 (:ocr_text)


## 声明

```lua
识别结果, 结果详情 = 图片:ocr_text([ 引擎选项, 二值化选项 ])
```


## 参数

- 引擎选项
    可选参数，表型，用于选择识别语言及识别引擎
    <details>

    <summary>参数结构</summary>

    ```lua
    {
        -- 如果将 engine 字段设为 "apple"，则使用 iOS 13 以上苹果自带的 Vision.framework 进行识别
        -- 你可以使用 image.vision_supported_recognition_languages() 函数获取 Vision.framework 支持的 OCR 模型列表
        -- 如果将 engine 字段设为 "paddle"，则使用 Paddle-Lite 引擎识别。可使用 lang 指定模型
        -- 例如 lang = "ppocr_ch" 则使用模型 /var/mobile/Media/1ferver/models/ppocr_ch
        -- Paddle-Lite 引擎支持 *.nb 格式的 Slim 模型
        engine = "apple" | "paddle" | "tesseract",
        lang = "zh-Hans",
    }
    ```
    </details>

    <details>

    <summary>各版本 iOS 内置的 Vision.framework 支持的 OCR 模型列表</summary>

    ```lua
    { -- iOS 13
        [1] = "en-US",
    }

    { -- iOS 14~15
        [1] = "en-US",
        [2] = "fr-FR",
        [3] = "it-IT",
        [4] = "de-DE",
        [5] = "es-ES",
        [6] = "pt-BR",
        [7] = "zh-Hans",
        [8] = "zh-Hant",
    }

    { -- iOS 16
        [ 1] = "en-US",
        [ 2] = "fr-FR",
        [ 3] = "it-IT",
        [ 4] = "de-DE",
        [ 5] = "es-ES",
        [ 6] = "pt-BR",
        [ 7] = "zh-Hans",
        [ 8] = "zh-Hant",
        [ 9] = "yue-Hans",
        [10] = "yue-Hant",
        [11] = "ko-KR",
        [12] = "ja-JP",
        [13] = "ru-RU",
        [14] = "uk-UA",
    }
    ```
    </details>

- 二值化选项
    实数型，二值化阈值，可参考 [图片自动二值化](/docs/handbook/image/imagem_cv_binaryzation.md)
    表型，自定义二值化色偏，参考 [图片手动二值化](/docs/handbook/image/imagem_binaryzation.md)
    文本型，自定义二值化色偏，参考 [图片手动二值化](/docs/handbook/image/imagem_binaryzation.md)


## 返回值

- 识别结果
    文本型，识别返回的文字
- 结果详情
    表型
    <details>

    <summary>OCR 识别的结果详情结构</summary>

    ```lua
    {
        {
            ["y"] = number_value,
            ["x"] = number_value,
            ["w"] = number_value,
            ["h"] = number_value,
            ["confidence"] = number_value(0.0000 ~ 1.0000),
            ["text"] = string_value,
        },
        ...
    }
    ```
    </details>


## 说明

> 识别图片中的文字，除了不需要区域参数，其它和 [屏幕区域文字识别 (screen.ocr_text)](/docs/handbook/screen/screen.ocr_text.md) 一致
> **软件版本在 1.3.8 以上可使用**
> [PaddleLite 简体中文普通版模型（需要解压缩）](https://xxtouch.lanzout.com/iL57a38ww71e)
> [PaddleLite 简体中文完全版模型（需要解压缩）](https://xxtouch.lanzout.com/iiQYx38ww6fc)
> [PaddleLite 繁体中文识别模型（需要解压缩）](https://xxtouch.lanzout.com/iNNpU38wyb3c)
> [PaddleLite 日文识别模型（需要解压缩）](https://xxtouch.lanzout.com/iYXfK3boux0h)
> [PaddleLite 韩文识别模型（需要解压缩）](https://xxtouch.lanzout.com/ieCCH3bouxda)
> [PaddleLite 英文数字识别模型（需要解压缩）](https://xxtouch.lanzout.com/iiKtE3994q8f)
> 也可从 [PaddleOCR 模型列表](https://gitee.com/paddlepaddle/PaddleOCR/blob/release/2.4/doc/doc_ch/models_list.md) 下载对应模型转换成 `det_opt.nb`、`cls_opt.nb`、`rec_opt.nb`, 然后找到对应的 [`dict.txt`](https://gitee.com/paddlepaddle/PaddleOCR/tree/release/2.4/ppocr/utils/dict) 配套使用

## 示例

```lua
-- 1.3.8 以上示例
local img = image.load_file(XXT_SCRIPTS_PATH..'/1.png')

txt, info = img:ocr_text("en-US")   -- iOS 13 以上可使用苹果内置的 en-US 模型识别英文数字
sys.toast("识别结果："..txt:atrim())

txt, info = img:ocr_text("zh-Hans") -- iOS 14 以上可使用苹果内置的 zh-Hans 模型识别简体中文
sys.toast("识别结果："..txt:atrim())

txt, info = img:ocr_text({
    engine = "apple", -- 使用 Apple 引擎
    lang = "zh-Hans"  -- 使用简体中文识别模型
}, "9D5D39-0F1F26,D3D3D2-2C2C2D")
sys.toast("识别结果："..txt:atrim())

txt, info = img:ocr_text({
    engine = "paddle", -- 使用 PaddleLite OCR 引擎
    lang = "ppocr_ch", -- 使用 ppocr_ch 模型
})
sys.toast("识别结果："..txt:atrim())
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`string.atrim`](/docs/handbook/ext-string/string.atrim.md)


## 旧版遗留示例（不推荐）

```lua
local img = image.load_file(XXT_SCRIPTS_PATH..'/1.png')
-- 示例 1：
local txt = img:ocr_text() -- 默认配置是使用 tesseract 引擎英文数字模式识别文字
sys.toast("识别结果："..txt:atrim())
--
-- 示例 2：
local txt = img:ocr_text("eng", "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
sys.toast("识别结果："..txt:atrim())
--
-- 示例 3：
local txt = img:ocr_text("eng", { {0x9D5D39, 0x0F1F26}, {0xD3D3D2, 0x2C2C2D} }) -- 使用色偏二值化识别，同上
sys.toast("识别结果："..txt:atrim())
--
-- 示例 4：
local txt = img:ocr_text({
  lang = "chi_sim",         -- 使用 tesseract 引擎简体中文库识别（注意，简体中文库不是内置的）
  white_list = "你我他",      -- 白名单设为 "你我他"
})
sys.toast("识别结果："..txt:atrim())
--
-- 示例 5：
local txt = img:ocr_text({
  lang = "eng",
  white_list = "1234567890",      -- 自定义使用白名单限制仅识别为数字
}, "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
sys.toast("识别结果："..txt:atrim())
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`string.atrim`](/docs/handbook/ext-string/string.atrim.md)

---

Source: [允许 App 请求跟踪 (sys.user_tracking / sys.set_user_tracking)](https://xxtouch.app/docs/handbook/sys/sys.user_tracking.md)
Path: handbook/sys/sys.user_tracking.md

# 允许 App 请求跟踪 (sys.user_tracking / sys.set_user_tracking)

> **该函数在 20260529 以后版本方可使用**

## 声明

```lua
允许请求跟踪 = sys.user_tracking()
设置成功 = sys.set_user_tracking(允许请求跟踪)
```

## 参数

- 允许请求跟踪
    布尔型，是否允许 App 请求跟踪。`true` 表示允许，`false` 表示不允许。

## 返回值

- 允许请求跟踪
    布尔型 或 nil，当前是否允许 App 请求跟踪；读取失败时返回 `nil`。
- 设置成功
    布尔型，是否设置成功。

## 说明

> 读取或设置 `设置 > 隐私与安全性 > 跟踪 > 允许 App 请求跟踪` 开关。
> 不同 iOS 版本中，该设置项的名称或位置可能略有不同。

## 示例

```lua
local allow = sys.user_tracking()

if type(allow) == "boolean" then
    sys.set_user_tracking(false)

    -- 需要恢复原状态时
    sys.set_user_tracking(allow)
else
    sys.toast("无法读取跟踪设置")
end
```

---

Source: [切换控件状态 (ui_element.toggle)](https://xxtouch.app/docs/handbook/ui_element/ui_element.toggle.md)
Path: handbook/ui_element/ui_element.toggle.md

# 切换控件状态 (ui_element.toggle)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.toggle(选择器或元素 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 用于切换开关、勾选框或其它能读取确认状态的控件。
> 如果无法读取目标状态，可能返回 `nil, "state unavailable"`。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.toggle({
    title = "飞行模式",
    role = "switch",
})
```

---

Source: [关闭设备蓝牙 (device.turn_off_bluetooth)](https://xxtouch.app/docs/handbook/device/device.turn_off_bluetooth.md)
Path: handbook/device/device.turn_off_bluetooth.md

# 关闭设备蓝牙 (device.turn_off_bluetooth)


## 声明

```lua
device.turn_off_bluetooth()
```

## 示例

```lua
device.turn_off_bluetooth()
```

---

Source: [递归创建目录 (file.mkdir_p)](https://xxtouch.app/docs/handbook/file/file.mkdir_p.md)
Path: handbook/file/file.mkdir_p.md

# 递归创建目录 (file.mkdir_p)


## 声明

```lua
操作成败, 错误信息 = file.mkdir_p(目录路径 [, 用户ID , 用户组ID , 权限 ])
```


## 参数

- 目录路径
    文本型
- 用户 ID
    整数型，可选参数，默认 501
- 用户组 ID
    整数型，可选参数，默认 501
- 权限
    整数型 | 文本型，可选参数，默认 "0777"


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 递归创建目录；未指定参数时，新建目录的所有者 UID/GID 为 501、权限为 八进制 0777
> 关键词：新建文件夹、创建文件夹
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local success, err = file.mkdir_p("/var/mobile/Media/1ferver/lua/scripts/a/b/c/d")
if success then
    sys.alert("创建成功")
else
    sys.alert("创建失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [解码一个二维码图片 (:qr_decode)](https://xxtouch.app/docs/handbook/image/imagem_qr_decode.md)
Path: handbook/image/imagem_qr_decode.md

# 解码一个二维码图片 (:qr_decode)


## 声明

```lua
识别文本 = 图片:qr_decode()
```


## 返回值

- 识别文本
    文本型 或 nil，返回当前二维码解码之后的文字，如果不是二维码或不能解码则返回 nil


## 说明

> 解码一张包含二维码的图片；图片可以包含少量干扰元素，不要求是纯二维码。


## 示例

```lua
-- 解码一个本地二维码图片文件
local img = image.load_file("/var/mobile/qr.png")
if img then
    local str = img:qr_decode()
    img:destroy()
    if str then
        sys.alert("识别成功\n识别结果是："..str)
    else
        sys.alert("识别失败")
    end
else
    sys.alert("图片文件加载失败，文件或许不存在")
end
```
```lua
-- 解码当前屏幕上显示的二维码
local str = screen.image():qr_decode()
if str then
    sys.alert("识别成功\n识别结果是："..str)
else
    sys.alert("识别失败")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [个性化广告 (sys.personalized_advertising / sys.set_personalized_advertising)](https://xxtouch.app/docs/handbook/sys/sys.personalized_advertising.md)
Path: handbook/sys/sys.personalized_advertising.md

# 个性化广告 (sys.personalized_advertising / sys.set_personalized_advertising)

> **该函数在 20260529 以后版本方可使用**

## 声明

```lua
允许个性化广告 = sys.personalized_advertising()
设置成功 = sys.set_personalized_advertising(允许个性化广告)
```

## 参数

- 允许个性化广告
    布尔型，是否允许个性化广告。`true` 表示允许，`false` 表示不允许。

## 返回值

- 允许个性化广告
    布尔型 或 nil，当前是否允许个性化广告；读取失败时返回 `nil`。
- 设置成功
    布尔型，是否设置成功。

## 说明

> 读取或设置 `设置 > 隐私与安全性 > Apple 广告 > 个性化广告` 开关。
> 不同 iOS 版本中，该设置项的名称或位置可能略有不同。

## 示例

```lua
local allow = sys.personalized_advertising()

if type(allow) == "boolean" then
    sys.set_personalized_advertising(false)

    -- 需要恢复原状态时
    sys.set_personalized_advertising(allow)
else
    sys.toast("无法读取个性化广告设置")
end
```

---

Source: [设置勾选状态 (ui_element.set_checked)](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_checked.md)
Path: handbook/ui_element/ui_element.set_checked.md

# 设置勾选状态 (ui_element.set_checked)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.set_checked(选择器或元素, 勾选状态 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 勾选状态
    布尔型，`true` 表示设置为开启或选中，`false` 表示设置为关闭或未选中。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 如果目标已经是指定状态，接口会直接返回成功。
> 目标控件必须能提供可靠的确认状态。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.set_checked({
    title = "飞行模式",
    role = "switch",
}, false)
```

---

Source: [打开设备飞行模式 (device.turn_on_airplane)](https://xxtouch.app/docs/handbook/device/device.turn_on_airplane.md)
Path: handbook/device/device.turn_on_airplane.md

# 打开设备飞行模式 (device.turn_on_airplane)


## 声明

```lua
device.turn_on_airplane()
```


## 说明

> 打开设备飞行模式（启用后将断开所有无线网络连接）


## 示例

```lua
device.turn_on_airplane()
```

---

Source: [更新文件访问和修改时间 (file.touch)](https://xxtouch.app/docs/handbook/file/file.touch.md)
Path: handbook/file/file.touch.md

# 更新文件访问和修改时间 (file.touch)


## 声明

```lua
操作成败, 错误信息 = file.touch(文件路径 [, 访问时间 , 修改时间])
```


## 参数

- 文件路径
    文本型
- 访问时间
    整数型，可选参数，秒级时间戳，如果未指定，则使用 `os.time()`
- 修改时间
    整数型，可选参数，秒级时间戳，如果未指定，则使用 `访问时间`


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 更新文件访问和修改时间，等同于 lfs.touch
> **该函数在 20250705 以后版本方可使用**


## 示例

```lua
local success, err = file.touch("/var/mobile/Media/1ferver/lua/scripts/", os.time() - 86400 * 3, os.time() - 86400 * 2)
if success then
    sys.alert("更新成功")
else
    sys.alert("更新失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [销毁一个图片对象 (:destroy)](https://xxtouch.app/docs/handbook/image/imagem_destroy.md)
Path: handbook/image/imagem_destroy.md

# 销毁一个图片对象 (:destroy)


## 声明

```lua
图片:destroy()
```


## 说明

> 立即释放图片对象所占用的内存，销毁后该对象不可再被使用
> 该方法用于性能优化：在频繁创建新图片对象的场景下，建议主动调用本方法以避免内存持续增长导致系统压力
> 偶尔创建图片对象时无需调用本方法，Lua 自带的垃圾回收机制会在延迟一段时间后自动回收


## 示例

```lua
sys.alert("点击确定后 1 秒开始监控屏幕画面变化")
--
sys.msleep(1000)
--
local img = screen.image()
while 1 do
    local scn = screen.image()
    local x, y, s = scn:cv_find_image(img)
    scn:destroy()
    if s < 95 then
        break
    end
    sys.msleep(10)
end
--
sys.alert("检测到屏幕画面发生变化")
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [定位服务 (sys.location_services / sys.set_location_services)](https://xxtouch.app/docs/handbook/sys/sys.location_services.md)
Path: handbook/sys/sys.location_services.md

# 定位服务 (sys.location_services / sys.set_location_services)

> **该函数在 20260529 以后版本方可使用**

## 声明

```lua
定位服务已开启 = sys.location_services()
设置成功 = sys.set_location_services(定位服务已开启)
```

## 参数

- 定位服务已开启
    布尔型，是否开启定位服务。`true` 表示开启，`false` 表示关闭。

## 返回值

- 定位服务已开启
    布尔型 或 nil，当前是否开启定位服务；读取失败时返回 `nil`。
- 设置成功
    布尔型，是否设置成功。

## 说明

> 读取或设置 `设置 > 隐私与安全性 > 定位服务` 总开关。
> 不同 iOS 版本中，该设置项的名称或位置可能略有不同。

## 示例

```lua
local enabled = sys.location_services()

if type(enabled) == "boolean" then
    sys.set_location_services(false)

    -- 需要恢复原状态时
    sys.set_location_services(enabled)
else
    sys.toast("无法读取定位服务设置")
end
```

---

Source: [设置控件值 (ui_element.set_value)](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_value.md)
Path: handbook/ui_element/ui_element.set_value.md

# 设置控件值 (ui_element.set_value)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.set_value(选择器或元素, 值 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 值
    文本型、整数型、实数型或布尔型，要设置的控件值。
- 选项
    可选参数，表型，可参考 [通用选项说明](options.md)。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 该接口适用于支持直接设置值的控件。
> 滑块可尝试传入 `0.0 ~ 1.0` 的实数，也可尝试传入 `"50%"` 这样的百分比文本。
> 如果目标控件没有实际变化，可能返回 `nil, "value unchanged"`。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.set_value({
    role = "slider",
    index = 1,
}, 0.5)
```

---

Source: [关闭设备飞行模式 (device.turn_off_airplane)](https://xxtouch.app/docs/handbook/device/device.turn_off_airplane.md)
Path: handbook/device/device.turn_off_airplane.md

# 关闭设备飞行模式 (device.turn_off_airplane)


## 声明

```lua
device.turn_off_airplane()
```


## 说明

> 关闭设备飞行模式（关闭后将恢复无线网络连接）


## 示例

```lua
device.turn_off_airplane()
```

---

Source: [使用 ZIP 打包一些文件 (file.zip)](https://xxtouch.app/docs/handbook/file/file.zip.md)
Path: handbook/file/file.zip.md

# 使用 ZIP 打包一些文件 (file.zip)


## 声明

```lua
操作成败, 错误信息 = file.zip(zip_路径, 文件列表 [, 密码])
```


## 参数

- zip_路径
    文本型，要创建的 zip 文件保存路径
- 文件列表
    表型 | 文本型
    - 当为表时：每个元素是一个包含两个元素的表 `{ 源文件路径, 归档路径 }`，其中“归档路径”表示写入 zip 内部的相对路径
    - 当为字符串时：表示一个目录路径，将该目录内容打包进 zip
- 密码
    文本型，可选参数，若提供则创建加密 zip


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 将文件或目录压缩到一个 zip 文件中
> 当 `文件列表` 为表时，可精确控制每个条目写入 zip 内部的相对路径；当为字符串时，将该目录内容整体打包
> **该函数在 20250914 以后的版本方可使用**


## 示例

### 以“表”精确指定归档路径

```lua
local ok, err = file.zip(XXT_SCRIPTS_PATH.."/out.zip", {
    { XXT_SCRIPTS_PATH.."/data/readme.txt",  "docs/readme.txt" },
    { XXT_SCRIPTS_PATH.."/assets/logo.png",  "assets/images/logo.png" },
}, "123456")
if not ok then
    sys.alert("打包失败："..err)
else
    sys.alert("打包成功："..XXT_SCRIPTS_PATH.."/out.zip")
end
```

### 直接打包一个目录

```lua
local ok, err = file.zip(XXT_SCRIPTS_PATH.."/project.zip", XXT_SCRIPTS_PATH.."/project")
if not ok then
    sys.alert("打包失败："..err)
else
    sys.alert("打包成功："..XXT_SCRIPTS_PATH.."/project.zip")
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [cv - 图中找图 (:cv_find_image)](https://xxtouch.app/docs/handbook/image/imagem_cv_find_image.md)
Path: handbook/image/imagem_cv_find_image.md

# cv - 图中找图 (:cv_find_image)


## 声明

```lua
横坐标, 纵坐标, 相似度 = 大图:cv_find_image(小图)
```


## 参数

- 小图
    图片对象，需要找的小图


## 返回值

- 横坐标, 纵坐标
    整数型，找到的小图在大图上的最匹配的位置的左上角坐标
- 相似度
    实数型，返回找到的小图在大图上的最匹配的位置的相似度，范围 0~100


## 说明

> opencv 扩展功能，在一个图片对象中找另外一个图片对象位置

---

Source: [增加控件值 (ui_element.increase)](https://xxtouch.app/docs/handbook/ui_element/ui_element.increase.md)
Path: handbook/ui_element/ui_element.increase.md

# 增加控件值 (ui_element.increase)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.increase(选择器或元素 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 选项
    可选参数，表型。可使用 `steps` 指定步进参数。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 用于滑块、滚轮等支持增减调节的控件。
> 每次增加的幅度由目标控件决定。需要精确控制时，应在 Lua 脚本中循环调用并读取结果。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.increase({
    role = "slider",
    index = 1,
})
```

---

Source: [连接到当前设置所选 VPN (device.turn_on_vpn)](https://xxtouch.app/docs/handbook/device/device.turn_on_vpn.md)
Path: handbook/device/device.turn_on_vpn.md

# 连接到当前设置所选 VPN (device.turn_on_vpn)


## 声明

```lua
device.turn_on_vpn()
```


## 说明

> 尝试连接到系统当前选中的 VPN；若未选中任何 VPN，调用无效
> **注**：该函数稳定性有限。**推荐**使用更稳定的方案：[VPN 配置模块 (vpnconf)](/docs/handbook/vpnconf/index.md)


## 示例

```lua
device.turn_on_vpn()
```

---

Source: [解压 ZIP 文件 (file.unzip)](https://xxtouch.app/docs/handbook/file/file.unzip.md)
Path: handbook/file/file.unzip.md

# 解压 ZIP 文件 (file.unzip)


## 声明

```lua
操作成败, 错误信息 = file.unzip(zip_路径, 解压缩到的路径 [, 密码])
```


## 参数

- zip_路径
    文本型，要解压缩的 zip 文件绝对路径
- 解压缩到的路径
    文本型，解压输出的目标目录
- 密码
    文本型，可选参数，若 zip 设置了密码则需提供


## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时的错误信息


## 说明

> 解压缩一个 zip 文件到指定路径
> 解压缩后的文件权限设置为 0755，文件所有者设置为 501，所属组设置为 501
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local ok, err = file.unzip(XXT_SCRIPTS_PATH.."/archive.zip", XXT_SCRIPTS_PATH.."/unzipped", "123456")
if not ok then
    sys.alert("解压失败："..err)
else
    sys.alert("解压成功："..XXT_SCRIPTS_PATH.."/unzipped")
end
```

```lua
-- 无密码示例
local ok, err = file.unzip(XXT_SCRIPTS_PATH.."/project.zip", XXT_SCRIPTS_PATH.."/project")
if not ok then
    sys.alert("解压失败："..err)
end
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [cv - 图片自动二值化 (:cv_binaryzation)](https://xxtouch.app/docs/handbook/image/imagem_cv_binaryzation.md)
Path: handbook/image/imagem_cv_binaryzation.md

# cv - 图片自动二值化 (:cv_binaryzation)


## 声明

```lua
图片 = 图片:cv_binaryzation([ 二值化阈值 ])
```


## 参数

- 二值化阈值
    实数型，可选参数，阈值，范围 0~255，默认选理论上最合适的阈值

## 返回值

- 图片
    图片对象，二值化后返回图片对象本体

## 说明

> opencv 扩展功能，图片自动二值化
> 会对对象本身产生影响
> 性能上，该函数操作过程不产生数据拷贝

---

Source: [减少控件值 (ui_element.decrease)](https://xxtouch.app/docs/handbook/ui_element/ui_element.decrease.md)
Path: handbook/ui_element/ui_element.decrease.md

# 减少控件值 (ui_element.decrease)

> **该函数在 20260507 以后版本方可使用**

## 声明

```lua
状态, 信息或错误信息 = ui_element.decrease(选择器或元素 [, 选项 ])
```

## 参数

- 选择器或元素
    表型，可以是 [选择器](selector.md)、查询返回的元素，或 `{ x = 横坐标, y = 纵坐标 }` 坐标表。
- 选项
    可选参数，表型。可使用 `steps` 指定步进参数。

## 返回值

- 状态
    布尔型，成功时为 `true`，失败时为 `nil`。
- 信息或错误信息
    成功时为表型动作信息，失败时为文本型错误原因。

## 说明

> 用于滑块、滚轮等支持增减调节的控件。
> 每次减少的幅度由目标控件决定。需要精确控制时，应在 Lua 脚本中循环调用并读取结果。

## 示例

```lua
local ui_element = require("ui_element")

ui_element.decrease({
    role = "picker",
    index = 1,
}, {
    steps = 2,
})
```

---

Source: [断开已有的 VPN 连接 (device.turn_off_vpn)](https://xxtouch.app/docs/handbook/device/device.turn_off_vpn.md)
Path: handbook/device/device.turn_off_vpn.md

# 断开已有的 VPN 连接 (device.turn_off_vpn)


## 声明

```lua
device.turn_off_vpn()
```


## 说明

> 断开已连接的 VPN；若当前无正在连接或已连接的 VPN，调用无效
> **注**：该函数稳定性有限，有可能调用无效。**推荐**使用更稳定的方案：[VPN 配置模块 (vpnconf)](/docs/handbook/vpnconf/index.md)


## 示例

```lua
device.turn_off_vpn()
```

---

Source: [将 GBK 编码的文本转成 UTF-8 编码的文本 (string.from_gbk)](https://xxtouch.app/docs/handbook/ext-string/string.from_gbk.md)
Path: handbook/ext-string/string.from_gbk.md

# 将 GBK 编码的文本转成 UTF-8 编码的文本 (string.from_gbk)


## 声明

```lua
可以直接用的文本 = string.from_gbk(GBK编码的文本)
```


## 参数

- GBK 编码的文本
    文本型，需要转换成 UTF-8 编码的 GBK 编码文本

## 返回值

- 可以直接用的文本
    字符串型 或 nil，返回 UTF-8 编码的文本，如果编码错误导致转换无法完成，返回 nil


## 说明

> 将 GBK 编码的文本转成 UTF-8 编码的文本
> 若输入本身编码不正确，函数仍会按映射完成字节转换，输出的乱码不是函数的问题
> 更复杂的编码转换需求请参考 [luaiconv（编码转换库）](/docs/handbook/open-source/luaiconv.md)
> 注：GBK 编码包含 GB2312 编码，因此 GB2312 文本也使用本函数转换


## 示例

```lua
-- 中文编码 中文标准编码 国标扩展编码 GB2312
gbkstr = '\x58\x58\x54\x6f\x75\x63\x68\x20\xba\xdc\xc7\xbf'
--
sys.alert(gbkstr)                  -- GBK 编码的字符串无法显示
sys.alert(string.from_gbk(gbkstr)) -- 输出 "XXTouch 很强"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)
**说明**：在 Lua 源码中，字符串中 `\x` 开头，后面跟两位 16 进制数表示以该数字编码的单个字节。例如：`\x58` 表示 `X` 这个字符，可打印字符部分参考[《ASCII 编码》](https://baike.baidu.com/item/ASCII/309296)

---

Source: [分解路径组成部分 (file.path.components)](https://xxtouch.app/docs/handbook/file/file.path.components.md)
Path: handbook/file/file.path.components.md

# 分解路径组成部分 (file.path.components)


## 声明

```lua
组成部分, 错误信息 = file.path.components(路径)
```


## 参数

- 路径
    文本型，要分解的路径字符串


## 返回值

- 组成部分
    顺序表型 或 nil，成功时返回由各路径组成部分构成的文本型数组，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 将路径字符串分解为其组成部分，按路径中的先后顺序返回
> 绝对路径的根目录 `/` 会作为一个独立的组成部分
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local components = file.path.components("/usr/local/bin")
-- 返回 {"/", "usr", "local", "bin"}
```

---

Source: [cv - 从图片创建一个拉伸的另外尺寸的图片 (:cv_resize)](https://xxtouch.app/docs/handbook/image/imagem_cv_resize.md)
Path: handbook/image/imagem_cv_resize.md

# cv - 从图片创建一个拉伸的另外尺寸的图片 (:cv_resize)


## 声明

```lua
图片 = 图片:cv_resize(宽, 高)
```


## 参数

- 宽, 高
    整数型，设定的新图片宽高

## 返回值

- 图片
    图片对象，返回更改尺寸后的图片对象本体


## 说明

> opencv 扩展功能，从图片创建一个更改尺寸的另外尺寸的图片
> 会对对象本身产生影响

---

Source: [判断当前是否打开了 VPN 开关 (device.is_vpn_on)](https://xxtouch.app/docs/handbook/device/device.is_vpn_on.md)
Path: handbook/device/device.is_vpn_on.md

# 判断当前是否打开了 VPN 开关 (device.is_vpn_on)


## 声明

```lua
开关状态, 状态描述 = device.is_vpn_on()
```


## 返回值

- 开关状态
    布尔型，VPN 开关处于打开状态（正在连接或已连接成功）返回 true，否则返回 false
- 状态描述
    文本型 或 nil，当开关状态为 true 时，返回描述当前 VPN 连接状态的字符串


## 说明

> **注意**：
> 当 VPN 正在连接（尚未连接成功）时，开关状态 也会返回 true。
> 状态描述 在不同语言环境或系统版本中可能不同，不保证一致性。
> 更多 VPN 相关功能参见 [VPN 配置模块 (vpnconf)](/docs/handbook/vpnconf/index.md)


## 示例

```lua
while (true) do
    local is_on, stat = device.is_vpn_on()
    if (is_on) then
        sys.toast(stat)
    else
        device.turn_on_vpn()
    end
end
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)

---

Source: [获取路径的最后一个组成部分 (file.path.last_component)](https://xxtouch.app/docs/handbook/file/file.path.last_component.md)
Path: handbook/file/file.path.last_component.md

# 获取路径的最后一个组成部分 (file.path.last_component)


## 声明

```lua
最后组成部分, 错误信息 = file.path.last_component(路径)
```


## 参数

- 路径
    文本型，路径字符串


## 返回值

- 最后组成部分
    文本型 或 nil，成功时返回路径的最后一个组成部分，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 返回路径的最后一个组成部分；对于根目录 `/`，返回 `/`
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local last = file.path.last_component("/usr/local/bin") -- 返回 "bin"
local root = file.path.last_component("/") -- 返回 "/"
```

---

Source: [cv - 图片对比 (:cv_compare_image)](https://xxtouch.app/docs/handbook/image/imagem_cv_compare_image.md)
Path: handbook/image/imagem_cv_compare_image.md

# cv - 图片对比 (:cv_compare_image)

## 声明

```lua
差异形状集合, 可视化图像 = 图片:cv_compare_image(另一个图片[, 比图配置])
```

## 参数

- 另一个图片
    图片对象，需要对比的对比图片

- 比图配置
    表型

    <details>

    <summary>比图配置字段</summary>

    ```Lua
    {
        should_visualize = false | true,  -- 可选参数，是否可视化输出，默认 false
        approx_epsilon = integer_value,   -- 可选参数，轮廓逼近周长百分率，用于将复杂轮廓简化，默认 2
    }
    ```
    </details>

## 返回值

- 差异形状集合
    表型，两个图片差异形状

    <details>

    <summary>形状集合结构</summary>

    ```Lua
    {
        { -- 形状 1
            { -- 形状 1 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 1 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        { -- 形状 2
            { -- 形状 2 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 2 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        ...
    }
    ```
    </details>

- 可视化图像
    图片对象，当 options.should_visualize 为 true 时，这个返回值是可视化返回值，它是个图片对象


## 说明

与另外一个图片对比两个图片的不同，并返回不同区域的形状顶点信息
两张图片尺寸必须一致


## 示例

```Lua
local cv = require("image.cv")
local img1 = image.load_file(XXT_SCRIPTS_PATH..'/1.png')
local img2 = image.load_file(XXT_SCRIPTS_PATH..'/2.png')
-- 返回值是一个形状列表，可能包含多个形状
local shapes, visimg = img1:cv_compare_image(img2)
nLog(shapes) -- 输出形状列表顶点信息
dialog():add_image(visimg):show() -- 可视化查看差异形状图片
```

---

Source: [打开设备闪光灯 (device.flash_on)](https://xxtouch.app/docs/handbook/device/device.flash_on.md)
Path: handbook/device/device.flash_on.md

# 打开设备闪光灯 (device.flash_on)


## 声明

```lua
是否成功 = device.flash_on()
```

## 返回值

- 是否成功
    布尔型，设备具备闪光灯硬件且相机可用时返回 true，否则返回 false


## 说明

> **iPad Pro 的闪光灯无法开启**
> 打开设备闪光灯。脚本终止时，由脚本开启的闪光灯会自动关闭


## 示例

```lua
device.flash_on()
```

---

Source: [删除路径的最后一个组成部分 (file.path.remove_last_component)](https://xxtouch.app/docs/handbook/file/file.path.remove_last_component.md)
Path: handbook/file/file.path.remove_last_component.md

# 删除路径的最后一个组成部分 (file.path.remove_last_component)


## 声明

```lua
新路径, 错误信息 = file.path.remove_last_component(路径)
```


## 参数

- 路径
    文本型，原始路径字符串


## 返回值

- 新路径
    文本型 或 nil，成功时返回删除最后一个组成部分后的路径字符串，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 删除路径的最后一个组成部分并返回新路径
> 对于 `/usr`，返回 `/`；对于根目录 `/`，仍返回 `/`
> 此函数只处理路径字符串，不会删除实际的文件或目录
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local parent = file.path.remove_last_component("/usr/local/bin") -- 返回 "/usr/local"
local root = file.path.remove_last_component("/usr") -- 返回 "/"
local unchanged = file.path.remove_last_component("/") -- 返回 "/"
```

---

Source: [cv - 图片转换成形状轮廓信息 (:cv_to_shapes)](https://xxtouch.app/docs/handbook/image/imagem_cv_to_shapes.md)
Path: handbook/image/imagem_cv_to_shapes.md

# cv - 图片转换成形状轮廓信息 (:cv_to_shapes)

## 声明

```lua
形状集合, 可视化图像 = 图片:cv_to_shapes([轮廓匹配配置])
```

## 参数

  - 轮廓匹配配置
    可选参数，表型

    <details>

    <summary>轮廓匹配配置字段</summary>

    ```Lua
    {
        should_visualize = false | true,  -- 可选参数，是否可视化输出，默认 false
        closed = false | true,            -- 可选参数，是否闭合图形，默认 false
        blur_size = integer_value,        -- 可选参数，模糊内核像素，只能为正奇数，默认 3
        canny_threshold1 = 100,           -- 可选参数，边缘最小阈值，默认 100
        canny_threshold2 = 200,           -- 可选参数，边缘最大阈值，默认 200
        approx_epsilon = integer_value,   -- 可选参数，轮廓逼近周长百分率，用于将复杂轮廓简化，默认 2
    }
    ```
    </details>

## 返回值

  - 形状集合
    表型，图片上的形状们的顶点信息

    <details>

    <summary>形状形状集合结构</summary>


    ```Lua
    {
        { -- 形状 1
            { -- 形状 1 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 1 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        { -- 形状 2
            { -- 形状 2 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 2 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        ...
    }
    ```
    </details>


  - 可视化图像
    图片对象，当 options.should_visualize 为 true 时，这个返回值是可视化返回值，它是个图片对象

## 说明

将图片上的轮廓转换成形状顶点信息
建议需要转换成形状的图片不要搞太复杂，最好是轮廓分明的闭合图形

## 示例

```Lua
local cv = require("image.cv")
local img = image.load_file(XXT_SCRIPTS_PATH..'/1.png')
-- 返回值是一个形状列表，可能包含多个形状
local shapes, visimg = img:cv_to_shapes({
    blur_size = 3, -- 模糊内核尺寸
    approx_epsilon = 2, -- 抗毛刺率 0~100
    closed = true, -- 闭合图形
    should_visualize = true, -- 是否可视化输出，为 true 则第二个返回值是一张图片
})
nLog(shapes) -- 输出形状列表顶点信息
dialog():add_image(visimg):show() -- 可视化查看形状图片
```

---

Source: [关闭设备闪光灯 (device.flash_off)](https://xxtouch.app/docs/handbook/device/device.flash_off.md)
Path: handbook/device/device.flash_off.md

# 关闭设备闪光灯 (device.flash_off)


## 声明

```lua
是否成功 = device.flash_off()
```


## 返回值

- 是否成功
    布尔型，设备具备闪光灯硬件且相机可用时返回 true，否则返回 false


## 说明

> **iPad Pro 的闪光灯无法开启**
> 若闪光灯处于开启状态，该函数会将其关闭；否则不执行任何操作。


## 示例

```lua
if device.flash_off() then
    -- 设备有闪光灯
else
    -- 设备没闪光灯
end
```

---

Source: [追加路径组成部分 (file.path.add_component)](https://xxtouch.app/docs/handbook/file/file.path.add_component.md)
Path: handbook/file/file.path.add_component.md

# 追加路径组成部分 (file.path.add_component)


## 声明

```lua
新路径, 错误信息 = file.path.add_component(路径, 组成部分)
```


## 参数

- 路径
    文本型，基础路径字符串
- 组成部分
    文本型，要追加的路径组成部分


## 返回值

- 新路径
    文本型 或 nil，成功时返回追加组成部分后的路径字符串，路径或组成部分无效时返回 nil
- 错误信息
    文本型，路径或组成部分无效时返回 `"Invalid path"`


## 说明

> 在基础路径后追加指定的路径组成部分，自动处理连接处的路径分隔符 `/`
> 此函数只生成路径字符串，不会创建实际的文件或目录
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local full_path = file.path.add_component("/usr/local", "bin") -- 返回 "/usr/local/bin"
local tmp_path = file.path.add_component("/", "tmp") -- 返回 "/tmp"
```

---

Source: [cv - 从图片找轮廓 (:cv_find_shapes)](https://xxtouch.app/docs/handbook/image/imagem_cv_find_shapes.md)
Path: handbook/image/imagem_cv_find_shapes.md

# cv - 从图片找轮廓 (:cv_find_shapes)

## 声明

```lua
查找到的形状信息, 可视化图像 = 图片:cv_find_shapes(形状集合[, 找形状配置])
```

## 参数

  - 形状集合
    表型，需要搜索的一个或多个形状的顶点信息

    <details>

    <summary>形状集合结构</summary>

    ```Lua
    {
        { -- 形状 1
            { -- 形状 1 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 1 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        { -- 形状 2
            { -- 形状 2 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 形状 2 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            ...
        },
        ...
    }
    ```
    </details>


  - 找形状配置
    表型，可选参数，轮廓匹配配置

    <details>

    <summary>找形状配置字段</summary>

    ```Lua
    {
        should_visualize = false | true,  -- 可选参数，是否可视化输出，默认 false
        closed = false | true,            -- 可选参数，是否闭合图形，默认 false
        min_area = number_value,          -- 可选参数，最小面积，默认 -1 不限制
        max_area = number_value,          -- 可选参数，最大面积，默认 -1 不限制
        blur_size = integer_value,        -- 可选参数，模糊内核像素，只能为正奇数，默认 3
        canny_threshold1 = 100,           -- 可选参数，边缘最小阈值，默认 100
        canny_threshold2 = 200,           -- 可选参数，边缘最大阈值，默认 200
        diff_threshold = number_value,    -- 可选参数，差值阈值，越小越相似，默认 0.001
        approx_epsilon = integer_value,   -- 可选参数，轮廓逼近周长百分率，用于将复杂轮廓简化，默认 2
    }
    ```
    </details>


## 返回值

  - 查找到的形状信息
    表型

    <details>

    <summary>查找到的形状信息结构</summary>

    ```Lua
    {
        { -- 与 形状 1 匹配的形状列表
            { -- 与 形状 1 匹配的第 1 个形状
                diff_score = number_value, -- 这个形状与 形状 1 的差异值，越小越相似
                { -- 与 形状 1 匹配的第 1 个形状 顶点 1
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                { -- 与 形状 1 匹配的第 1 个形状 顶点 2
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                ...
            },
            { -- 与 形状 1 匹配的第 2 个形状
                diff_score = number_value, -- 这个形状与 形状 1 的差异值，越小越相似
                { -- 与 形状 1 匹配的第 2 个形状 顶点 1
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                { -- 与 形状 1 匹配的第 2 个形状 顶点 2
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                ...
            },
            ...
        },
        { -- 与 形状 2 匹配的形状列表
            { -- 与 形状 2 匹配的第 1 个形状
                diff_score = number_value, -- 这个形状与 形状 2 的差异值，越小越相似
                { -- 与 形状 2 匹配的第 1 个形状 顶点 1
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                { -- 与 形状 2 匹配的第 1 个形状 顶点 2
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                ...
            },
            { -- 与 形状 2 匹配的第 2 个形状
                diff_score = number_value, -- 这个形状与 形状 2 的差异值，越小越相似
                { -- 与 形状 2 匹配的第 2 个形状 顶点 1
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                { -- 与 形状 2 匹配的第 2 个形状 顶点 2
                    ["y"] = number_value,
                    ["x"] = number_value,
                },
                ...
            },
            ...
        },
        ...
    }
    ```
    </details>


  - 可视化图像
    图片对象，当 options.should_visualize 为 true 时，这个返回值是可视化返回值，它是个图片对象

## 说明

从图片中查找一个或多个形状
标准规则形状可使用函数生成

## 示例

```Lua
function make_triangle(side_len) -- 创建等边三角形，只需要边长参数，自动生成 3 个顶点
    local hf = math.sqrt(3)/2
    local h = math.floor(hf * side_len)
    return {
        {
            ["x"] = 1,
            ["y"] = h,
        },
        {
            ["x"] = side_len,
            ["y"] = h,
        },
        {
            ["x"] = side_len // 2,
            ["y"] = 1,
        },
    }
end

function make_rectangle(side_len) -- 创建正方形，只需要边长参数，自动生成 4 个顶点
    return {
        { -- 左上
            ["x"] = 1,
            ["y"] = 1,
        },
        { -- 左下
            ["x"] = 1,
            ["y"] = side_len,
        },
        { -- 右下
            ["x"] = side_len,
            ["y"] = side_len,
        },
        { -- 右上
            ["x"] = side_len,
            ["y"] = 1,
        },
    }
end
-- 返回值是多个形状列表的列表，每个列表对应参数的形状找到的列表
-- 这里是查找等边三角形和正方形
local info, visimg = screen.image():cv_find_shapes({make_triangle(45), make_rectangle(40)}, {
    min_area = 2000,  -- 最小面积
    max_area = 20000, -- 最大面积
    diff_threshold = 0.005, -- 最大形变容差，越小越相似
    approx_epsilon = 1,
    shape_match_mode = 3,
    closed = true, -- 闭合图形
    should_visualize = true, -- 是否可视化输出，为 true 则第二个返回值是一张图片
})

nLog(info[1]) -- 输出与等边三角形匹配的形状列表
nLog(info[2]) -- 输出与正方形匹配的形状列表

dialog():add_image(visimg):show() -- 可视化输出图片
```

---

Source: [打开“减少动态效果”开关 (device.reduce_motion_on)](https://xxtouch.app/docs/handbook/device/device.reduce_motion_on.md)
Path: handbook/device/device.reduce_motion_on.md

# 打开“减少动态效果”开关 (device.reduce_motion_on)


## 声明

```lua
device.reduce_motion_on()
```


## 说明

> “减少动态效果”的开关位于设备的 **设置 → 通用 → 辅助功能 → 减少动态效果**


## 示例

```lua
device.reduce_motion_on()
```

---

Source: [获取路径的文件扩展名 (file.path.extension)](https://xxtouch.app/docs/handbook/file/file.path.extension.md)
Path: handbook/file/file.path.extension.md

# 获取路径的文件扩展名 (file.path.extension)


## 声明

```lua
扩展名, 错误信息 = file.path.extension(路径)
```


## 参数

- 路径
    文本型，路径字符串


## 返回值

- 扩展名
    文本型 或 nil，成功时返回不含前导 `.` 的扩展名，没有扩展名时返回空字符串 `""`，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 返回最后一个路径组成部分中的文件扩展名；存在多段扩展名时，只返回最后一段，例如 `archive.tar.gz` 返回 `gz`
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local ext = file.path.extension("/path/to/file.txt") -- 返回 "txt"
local archive_ext = file.path.extension("/path/to/archive.tar.gz") -- 返回 "gz"
local no_ext = file.path.extension("/path/to/file") -- 返回 ""
```

---

Source: [cv - 图片多模板特征检测 (:cv_detect_templates)](https://xxtouch.app/docs/handbook/image/imagem_cv_detect_templates.md)
Path: handbook/image/imagem_cv_detect_templates.md

# cv - 图片多模板特征检测 (:cv_detect_templates)

## 声明

```lua
结果集合, 可视化图像 = 图片:cv_detect_templates(小图片模板集合及选项)
```

## 参数

  - 小图片模板集合及选项
    可选参数，表型，表内每个顺序元素都是一个图片对象，命名字段是选项

    <details>

    <summary>选项字段</summary>

    ```Lua
    {
        should_visualize = false | true,  -- 可选字段，是否可视化输出，默认 false
        detector = 0 | 1 | 2,             -- 可选字段，特征检测器，0: ORB, 1: SIFT, 2: SURF，默认 0: ORB
        score_thresh = number_value,      -- 可选字段，百分制特征点匹配得分阈值，默认 90
    }
    ```
    </details>

## 返回值

  - 结果集合
    表型，图片上检测到的模板特征的信息集合

    <details>

    <summary>检测结果集合结构</summary>


    ```Lua
    {
        { -- 结果 1
            { -- 结果 1 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 1 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 1 顶点 3
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 1 顶点 4
                ["y"] = number_value,
                ["x"] = number_value,
            },
            confidence = number_value,  -- 结果 1 所有特征点综合置信度
            angle = number_value,       -- 旋转角度
            index = number_value,       -- 匹配的模板在小图片模板集合中的索引
        },
        { -- 结果 2
            { -- 结果 2 顶点 1
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 2 顶点 2
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 2 顶点 3
                ["y"] = number_value,
                ["x"] = number_value,
            },
            { -- 结果 2 顶点 4
                ["y"] = number_value,
                ["x"] = number_value,
            },
            confidence = number_value,  -- 结果 2 所有特征点综合置信度
            angle = number_value,       -- 旋转角度
            index = number_value,       -- 匹配的模板在小图片模板集合中的索引
        },
        ...
    }
    ```
    </details>


  - 可视化图像
    图片对象，当 options.should_visualize 为 true 时，这个返回值是可视化返回值，它是个图片对象

## 说明

从图片中检测出小图片模板集合中的图片特征，可用于形变旋转后的特征检测
每个小图片模板只会匹配到分数超过 score_thresh 的最优结果
**20250625 以上版本支持**

## 注意

参数中的 score_thresh 与返回值中的 confidence 有区别
score_thresh 是用于筛选特征点，confidence 是模板所有特征点综合置信度

## 示例

```Lua
local cv = require("image.cv")
local img1 = image.load_file(XXT_SCRIPTS_PATH..'/1.png')
local img2 = image.load_file(XXT_SCRIPTS_PATH..'/2.png')

local results, visimg = screen.image():cv_detect_templates({
    img1, img2;
    score_thresh = 90,
    detector = 1, -- SIFT
    should_visualize = true, -- 是否可视化输出，为 true 则第二个返回值是一张图片
})

nLog(results) -- 输出检测结果信息
dialog():add_image(visimg):show() -- 可视化查看检测结果图片
```

---

Source: [关闭“减少动态效果”开关 (device.reduce_motion_off)](https://xxtouch.app/docs/handbook/device/device.reduce_motion_off.md)
Path: handbook/device/device.reduce_motion_off.md

# 关闭“减少动态效果”开关 (device.reduce_motion_off)


## 声明

```lua
device.reduce_motion_off()
```


## 说明

> “减少动态效果”的开关位于设备的 **设置 → 通用 → 辅助功能 → 减少动态效果**


## 示例

```lua
device.reduce_motion_off()
```

---

Source: [删除路径的文件扩展名 (file.path.remove_extension)](https://xxtouch.app/docs/handbook/file/file.path.remove_extension.md)
Path: handbook/file/file.path.remove_extension.md

# 删除路径的文件扩展名 (file.path.remove_extension)


## 声明

```lua
新路径, 错误信息 = file.path.remove_extension(路径)
```


## 参数

- 路径
    文本型，原始路径字符串


## 返回值

- 新路径
    文本型 或 nil，成功时返回删除扩展名后的路径字符串，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 删除最后一个路径组成部分的扩展名及其前面的 `.`，存在多段扩展名时只删除最后一段；没有扩展名时返回原路径
> 此函数只处理路径字符串，不会重命名实际的文件或目录
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local base = file.path.remove_extension("/path/to/file.txt") -- 返回 "/path/to/file"
local archive_base = file.path.remove_extension("/path/to/archive.tar.gz") -- 返回 "/path/to/archive.tar"
local unchanged = file.path.remove_extension("/path/to/file") -- 返回 "/path/to/file"
```

---

Source: [打开 AssistiveTouch (device.assistive_touch_on)](https://xxtouch.app/docs/handbook/device/device.assistive_touch_on.md)
Path: handbook/device/device.assistive_touch_on.md

# 打开 AssistiveTouch (device.assistive_touch_on)


## 声明

```lua
device.assistive_touch_on()
```


## 说明

> AssistiveTouch 的开关位于设备的 **设置 → 通用 → 辅助功能 → AssistiveTouch**


## 示例

```lua
device.assistive_touch_on()
```

---

Source: [追加文件扩展名 (file.path.add_extension)](https://xxtouch.app/docs/handbook/file/file.path.add_extension.md)
Path: handbook/file/file.path.add_extension.md

# 追加文件扩展名 (file.path.add_extension)


## 声明

```lua
新路径, 错误信息 = file.path.add_extension(路径, 扩展名)
```


## 参数

- 路径
    文本型，基础路径字符串
- 扩展名
    文本型，要追加的文件扩展名，通常不包含前导 `.`


## 返回值

- 新路径
    文本型 或 nil，成功时返回追加扩展名后的路径字符串，无法追加时返回 nil
- 错误信息
    文本型，路径字符串无效时返回 `"Invalid path"`，扩展名字符串无效时返回 `"Invalid extension"`；扩展名包含 `/` 等导致无法追加时，可能只返回 nil 而不提供错误信息


## 说明

> 在路径末尾追加 `.` 和指定的扩展名；如果原路径已有扩展名，新扩展名会追加在现有扩展名之后，例如 `file.txt` 追加 `bak` 后为 `file.txt.bak`
> 传入的扩展名可以包含前导 `.`，但此函数不会去掉它；传入 `.txt` 会追加 `..txt`
> 此函数只生成路径字符串，不会重命名实际的文件或目录
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local new_path = file.path.add_extension("/path/to/file", "txt") -- 返回 "/path/to/file.txt"
local archive_path = file.path.add_extension("/path/to/file.tar", "gz") -- 返回 "/path/to/file.tar.gz"
local backup_path = file.path.add_extension("/path/to/file.txt", "bak") -- 返回 "/path/to/file.txt.bak"
local dotted_path = file.path.add_extension("/path/to/file", ".txt") -- 返回 "/path/to/file..txt"
```

---

Source: [关闭 AssistiveTouch (device.assistive_touch_off)](https://xxtouch.app/docs/handbook/device/device.assistive_touch_off.md)
Path: handbook/device/device.assistive_touch_off.md

# 关闭 AssistiveTouch (device.assistive_touch_off)


## 声明

```lua
device.assistive_touch_off()
```


## 说明

> AssistiveTouch 的开关位于设备的 **设置 → 通用 → 辅助功能 → AssistiveTouch**


## 示例

```lua
device.assistive_touch_off()
```

---

Source: [标准化路径 (file.path.normalize)](https://xxtouch.app/docs/handbook/file/file.path.normalize.md)
Path: handbook/file/file.path.normalize.md

# 标准化路径 (file.path.normalize)


## 声明

```lua
标准化路径, 错误信息 = file.path.normalize(路径)
```


## 参数

- 路径
    文本型，原始路径字符串


## 返回值

- 标准化路径
    文本型 或 nil，成功时返回标准化后的路径字符串，路径无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 标准化路径，处理路径中的 `.`、`..` 组成部分，并移除多余的斜杠
> 如需解析路径中的符号链接，请使用 [`file.path.resolve_symlinks`](/docs/handbook/file/file.path.resolve_symlinks.md)
> 此函数不会移动或重命名实际的文件或目录
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
local std_path = file.path.normalize("/usr/local/../bin/./script") -- 返回 "/usr/bin/script"
local clean_path = file.path.normalize("//tmp///file/") -- 返回 "/tmp/file"
```

---

Source: [获取背光亮度值 (device.brightness)](https://xxtouch.app/docs/handbook/device/device.brightness.md)
Path: handbook/device/device.brightness.md

# 获取背光亮度值 (device.brightness)


## 声明

```lua
亮度 = device.brightness()
```


## 返回值

- 亮度
    实数型，返回当前设备的背光亮度，范围 0.0~1.0


## 示例

参考 [`device.set_brightness`](/docs/handbook/device/device.set_brightness.md) 示例

---

Source: [解析路径中的符号链接 (file.path.resolve_symlinks)](https://xxtouch.app/docs/handbook/file/file.path.resolve_symlinks.md)
Path: handbook/file/file.path.resolve_symlinks.md

# 解析路径中的符号链接 (file.path.resolve_symlinks)


## 声明

```lua
解析后的路径, 错误信息 = file.path.resolve_symlinks(路径)
```


## 参数

- 路径
    文本型，包含符号链接的原始路径字符串


## 返回值

- 解析后的路径
    文本型 或 nil，成功时返回解析符号链接并标准化后的路径字符串，路径字符串无效时返回 nil
- 错误信息
    文本型，路径无效时返回 `"Invalid path"`


## 说明

> 解析路径中的符号链接，并对结果路径进行标准化；返回结果取决于设备上的实际符号链接关系
> 返回路径字符串不代表该路径一定存在；路径不存在或有无法解析的部分时，不保证返回 nil 或错误信息。如需判断是否存在，请使用 [`file.exists`](/docs/handbook/file/file.exists.md)
> **该函数在 20250914 以后的版本方可使用**


## 示例

```lua
-- 假设 /var/mobile/link 是指向 /var/mobile/Documents 的符号链接
local real_path = file.path.resolve_symlinks("/var/mobile/link/script.lua")
-- 返回 "/var/mobile/Documents/script.lua"
```

---

Source: [设置背光亮度 (device.set_brightness)](https://xxtouch.app/docs/handbook/device/device.set_brightness.md)
Path: handbook/device/device.set_brightness.md

# 设置背光亮度 (device.set_brightness)


## 声明

```lua
device.set_brightness(亮度)
```


## 参数

- 亮度
    实数型，用于设置设备的背光亮度，范围 0.0~1.0


## 说明

> 该函数调用会关闭设备的自动调整背光功能


## 示例

```lua
sys.toast(device.brightness())
for i = 1, 10 do
    device.set_brightness(i/10)
    sys.msleep(200)
end
for i = 10, 5, -1 do
    device.set_brightness(i/10)
    sys.msleep(200)
end
```
**注**：上述代码中使用了非本章函数 [`sys.toast`](/docs/handbook/sys/sys.toast.md)、[`sys.msleep`](/docs/handbook/sys/sys.msleep.md)

---

Source: [设置自动锁屏分钟数 (device.set_autolock_time)](https://xxtouch.app/docs/handbook/device/device.set_autolock_time.md)
Path: handbook/device/device.set_autolock_time.md

# 设置自动锁屏分钟数 (device.set_autolock_time)


## 声明

```lua
device.set_autolock_time(分钟数)
```


## 参数

- 分钟数
    整数型，用于设置设备自动锁屏分钟数，设置为 0 则永不锁屏


## 说明

> 只能设置为系统支持的分钟档位（与 **设置 → 显示与亮度 → 自动锁定** 中的选项一致）


## 示例

```lua
device.set_autolock_time(0)
```

---

Source: [计算字符串的 md5 哈希值 (string.md5)](https://xxtouch.app/docs/handbook/ext-string/string.md5.md)
Path: handbook/ext-string/string.md5.md

# 计算字符串的 md5 哈希值 (string.md5)


## 声明

```lua
哈希值 = string.md5(数据内容)
```


## 参数

- 数据内容
    字符串型，原始字符串

## 返回值

- 哈希值
    文本型，返回字符串的 md5 哈希值的 16 进制文本


## 说明

> 计算字符串 (或二进制数据块) 的 md5 校验值


## 示例

```lua
sys.alert(string.md5('XXTouch 真棒')) -- 输出 "4921dbf380df452fa959dc47cef30e4b"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [设置设备音量 (device.set_volume)](https://xxtouch.app/docs/handbook/device/device.set_volume.md)
Path: handbook/device/device.set_volume.md

# 设置设备音量 (device.set_volume)


## 声明

```lua
device.set_volume(音量)
```


## 参数

- 音量
    实数型，用于设置设备的音量，范围 0.0~1.0


## 示例

```lua
device.set_volume(0) -- 设备静音
```

---

Source: [! 加入到一个无线局域网 (device.join_wifi)](https://xxtouch.app/docs/handbook/device/device.join_wifi.md)
Path: handbook/device/device.join_wifi.md

# ! 加入到一个无线局域网 (device.join_wifi)


## 声明

```lua
操作成败, 错误信息 = device.join_wifi(SSID, 密码[, 超时毫秒])
```


## 参数

- SSID
    文本型，无线局域网的 SSID，也就是名字
- 密码
    文本型，无线局域网的密码
- 超时毫秒
    整数型，可选参数，超时的毫秒数，默认 10000

## 返回值

- 操作成败
    布尔型，操作成功返回 true，操作失败返回 false
- 错误信息
    文本型，操作失败时返回错误信息


## 说明

**这个函数在 20250317 以后的版本改为同步函数**


## 示例

```lua
local ok, err = device.join_wifi('Tenda_9B3F', '12345678')
```

---

Source: [遗忘一个无线局域网 (device.forget_wifi)](https://xxtouch.app/docs/handbook/device/device.forget_wifi.md)
Path: handbook/device/device.forget_wifi.md

# 遗忘一个无线局域网 (device.forget_wifi)


## 声明

```lua
是否成功 = device.forget_wifi(SSID)
```


## 参数

- SSID
    文本型，需要遗忘的无线局域网名称


## 返回值

- 是否成功
    布尔型，成功从已保存的无线局域网列表中移除则返回 true，否则返回 false


## 示例

```lua
local ok = device.forget_wifi('Tenda_9B3F')
```

---

Source: [计算字符串的 sha1 哈希值 (string.sha1)](https://xxtouch.app/docs/handbook/ext-string/string.sha1.md)
Path: handbook/ext-string/string.sha1.md

# 计算字符串的 sha1 哈希值 (string.sha1)


## 声明

```lua
哈希值 = string.sha1(数据内容)
```


## 参数

- 数据内容
    字符串型，原始字符串

## 返回值

- 哈希值
    文本型，返回字符串的 sha1 哈希值的 16 进制文本


## 说明

> 计算字符串 (或二进制数据块) 的 sha1 校验值


## 示例

```lua
sys.alert(string.sha1('XXTouch 真棒')) -- 输出 "a959c48d904c1075c7ddfdb1fda49effb2142493"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [计算字符串的 HMAC-SHA1 哈希值 (string.hmac_sha1)](https://xxtouch.app/docs/handbook/ext-string/string.hmac_sha1.md)
Path: handbook/ext-string/string.hmac_sha1.md

# 计算字符串的 HMAC-SHA1 哈希值 (string.hmac_sha1)


## 声明

```lua
hexHash = string.hmac_sha1(data, key)
```


## 参数

- data
    字符串型，用于计算哈希的数据内容
- key
    字符串型，HMAC 算法使用的密钥

## 返回值

- hexHash
    字符串型，返回 HMAC-SHA1 校验值的 16 进制小写文本


## 说明

> 使用 HMAC-SHA1 算法对任意字符串（或二进制数据）计算带密钥的哈希摘要


## 示例

```lua
local signature = string.hmac_sha1('hello world', 'secret')
sys.alert(signature) -- 输出 "03376ee7ad7bbfceee98660439a4d8b125122a5a"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [计算字符串的 HMAC-SHA256 哈希值 (string.hmac_sha256)](https://xxtouch.app/docs/handbook/ext-string/string.hmac_sha256.md)
Path: handbook/ext-string/string.hmac_sha256.md

# 计算字符串的 HMAC-SHA256 哈希值 (string.hmac_sha256)


## 声明

```lua
hexHash = string.hmac_sha256(data, key)
```


## 参数

- data
    字符串型，用于计算哈希的数据内容
- key
    字符串型，HMAC 算法使用的密钥

## 返回值

- hexHash
    字符串型，返回 HMAC-SHA256 校验值的 16 进制小写文本


## 说明

> 使用 HMAC-SHA256 算法对任意字符串（或二进制数据）计算带密钥的哈希摘要


## 示例

```lua
local signature = string.hmac_sha256('hello world', 'secret')
sys.alert(signature) -- 输出 "734cc62f32841568f45715aeb9f4d7891324e6d948e4c6c60c0621cdac48623a"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [对字符串进行 base64 编码 (string.base64_encode)](https://xxtouch.app/docs/handbook/ext-string/string.base64_encode.md)
Path: handbook/ext-string/string.base64_encode.md

# 对字符串进行 base64 编码 (string.base64_encode)


## 声明

```lua
b64文本 = string.base64_encode(数据内容)
```


## 参数

- 数据内容
    字符串型，原始字符串

## 返回值

- b64 文本
    文本型，返回字符串的 base64 编码文本


## 说明

> 对字符串（或二进制数据块）进行 Base64 编码
> 关键词：图片 Base64、文件 Base64、数据 Base64、二进制 Base64


## 示例

```lua
-- 取屏幕区域 png 格式数据进行 base64 编码
b64s = screen.image(0, 0, 100, 100):png_data():base64_encode()

-- 读取文件数据并进行 base64 编码
b64s = file.reads('/var/mobile/1.png'):base64_encode()
```
**注**：上述代码中使用了非本章函数 [`screen.image`](/docs/handbook/screen/screen.image.md)、[`:png_data`](/docs/handbook/image/imagem_png_data.md)、[`file.reads`](/docs/handbook/file/file.reads.md)


## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [对 base64 编码的文本进行解码 (string.base64_decode)](https://xxtouch.app/docs/handbook/ext-string/string.base64_decode.md)
Path: handbook/ext-string/string.base64_decode.md

# 对 base64 编码的文本进行解码 (string.base64_decode)


## 声明

```lua
数据内容 = string.base64_decode(b64文本)
```


## 参数

- b64 文本
    文本型，base64 编码的文本

## 返回值

- 数据内容
    字符串型，返回解码后的字符串


## 说明

> `string.base64_encode` 的反函数；将 Base64 文本解码回原始字符串（或二进制数据块）


## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [对 URI 进行编码 (string.encode_uri)](https://xxtouch.app/docs/handbook/ext-string/string.encode_uri.md)
Path: handbook/ext-string/string.encode_uri.md

# 对 URI 进行编码 (string.encode_uri)


## 声明

```lua
编码后的URI = string.encode_uri(URI)
```


## 参数

- URI
    字符串型，URI

## 返回值

- 编码后的 URI
    文本型，返回编码后的 URI


## 说明

> 对 URI 中的特殊字符进行百分号编码（percent-encoding）
> 关键词：URL 编码、URI 编码
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.encode_uri("https://www.example.com/测试")) -- https://www.example.com/%E6%B5%8B%E8%AF%95
```

---

Source: [对 URI 进行解码 (string.decode_uri)](https://xxtouch.app/docs/handbook/ext-string/string.decode_uri.md)
Path: handbook/ext-string/string.decode_uri.md

# 对 URI 进行解码 (string.decode_uri)


## 声明

```lua
URI = string.decode_uri(编码后的URI)
```


## 参数

- 编码后的 URI
    文本型，编码后的 URI

## 返回值

- URI
    字符串型，返回解码后的 URI


## 说明

> `string.encode_uri` 的反函数，将百分号编码后的 URI 解码回原始字符串
> 关键词：URL 解码、URI 解码
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.decode_uri("https://www.example.com/%E6%B5%8B%E8%AF%95")) -- https://www.example.com/测试
```

---

Source: [对 URI 组件进行编码 (string.encode_uri_component)](https://xxtouch.app/docs/handbook/ext-string/string.encode_uri_component.md)
Path: handbook/ext-string/string.encode_uri_component.md

# 对 URI 组件进行编码 (string.encode_uri_component)


## 声明

```lua
编码后的URI组件 = string.encode_uri_component(URI组件)
```


## 参数

- URI 组件
    字符串型，URI 组件

## 返回值

- 编码后的 URI 组件
    文本型，返回编码后的 URI 组件


## 说明

> 对 URI 组件中的特殊字符进行百分号编码；相比 `string.encode_uri`，会更为严格地转义 `/`、`?`、`&`、`=` 等保留字符
> 关键词：URI 组件编码
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.encode_uri_component("https://www.example.com/测试")) -- https%3A%2F%2Fwww.example.com%2F%E6%B5%8B%E8%AF%95
```

---

Source: [对 URI 组件进行解码 (string.decode_uri_component)](https://xxtouch.app/docs/handbook/ext-string/string.decode_uri_component.md)
Path: handbook/ext-string/string.decode_uri_component.md

# 对 URI 组件进行解码 (string.decode_uri_component)


## 声明

```lua
URI组件 = string.decode_uri_component(编码后的URI组件)
```


## 参数

- 编码后的 URI 组件
    文本型，编码后的 URI 组件


## 返回值

- URI 组件
    字符串型，返回解码后的 URI 组件字符串


## 说明

> `string.encode_uri_component` 的反函数，将编码后的 URI 组件解码回原始内容
> 关键词：URI 组件解码
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.decode_uri_component("https://www.example.com/%E6%B5%8B%E8%AF%95")) -- https://www.example.com/测试
```

---

Source: [对字符串进行加密 (string.aes128_encrypt)](https://xxtouch.app/docs/handbook/ext-string/string.aes128_encrypt.md)
Path: handbook/ext-string/string.aes128_encrypt.md

# 对字符串进行加密 (string.aes128_encrypt)

> **不推荐使用：** 该函数仅保留用于兼容旧脚本。新脚本建议使用 [lua-openssl 扩展库](../open-source/lua-openssl.md)，按需要选择 `aes-128-ecb`、`aes-128-gcm` 等算法。


## 声明

```lua
加密的数据 = string.aes128_encrypt(数据内容, 密钥)
```


## 参数

- 数据内容
    字符串型，需要加密的字符串
- 密钥
    字符串型，密码

## 返回值

- 加密的数据
    字符串型，加密后的二进制数据块


## 说明

> 使用 AES128-ECB 算法对字符串（或二进制数据块）进行加密
> 注：ECB 模式本身不需要 IV（初始向量）参数；若第三方系统要求填写 IV，传入 `0` 即可

## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [解密一段已加密的字符串 (string.aes128_decrypt)](https://xxtouch.app/docs/handbook/ext-string/string.aes128_decrypt.md)
Path: handbook/ext-string/string.aes128_decrypt.md

# 解密一段已加密的字符串 (string.aes128_decrypt)

> **不推荐使用：** 该函数仅保留用于兼容旧脚本。新脚本建议使用 [lua-openssl 扩展库](../open-source/lua-openssl.md)，按需要选择 `aes-128-ecb`、`aes-128-gcm` 等算法。


## 声明

```lua
数据内容 = string.aes128_decrypt(加密的数据, 密钥)
```


## 参数

- 加密的数据
    字符串型，已经加密的字符串
- 密钥
    字符串型，密码

## 返回值

- 数据内容
    字符串型，解密之后的字符串


## 说明

> 使用 AES128-ECB 算法对密文字符串（或二进制数据块）进行解密
> 注：ECB 模式本身不需要 IV（初始向量）参数；若第三方系统要求填写 IV，传入 `0` 即可

## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [用分隔符规则分割一个字符串 (string.split)](https://xxtouch.app/docs/handbook/ext-string/string.split.md)
Path: handbook/ext-string/string.split.md

# 用分隔符规则分割一个字符串 (string.split)


## 声明

```lua
分割好的文本数组 = string.split(待分割文本, 分隔符)
```


## 参数

- 待分割文本
    文本型，需要分割的字符串
- 分隔符
    文本型，分隔符

## 返回值

- 分割好的文本数组
    表型，分割后的字符串片段按顺序排列于此表


## 说明

> 用分隔符规则分割一个字符串
> 关键词：字符串分割、文本分割、文本切割、文本分段


## 示例

```lua
-- 示例   1 (分割账号密码) ：
t = string.split('lfue6841214----123456', '----')
sys.alert('账号是：'..t[1])
--
-- 示例   2 (取文本中间部分，两个 # 之间的文字) ：
t = string.split('您好，验证码是#4937#，15分钟内有效。【爆炸科技】', '#')
sys.alert('验证码是：'..t[2])
--
-- 示例   3 (复杂点的取文本中间部分) ：
t = string.split('您好，验证码是4937，15分钟内有效。【爆炸科技】', '验证码是')
t = string.split(t[2], '，15分钟')
sys.alert('验证码是：'..t[1])
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 封装示例 1

```lua
-- 取文本中间部分的封装 (找不到匹配返回 nil)
function str_middle(str, sep1, sep2)
    assert(type(str) == 'string', '`str_middle` 第 #1 参数必须是字符串')
    assert(type(sep1) == 'string', '`str_middle` 第 #2 参数必须是字符串')
    assert(type(sep2) == 'nil' or type(sep2) == 'string', '`str_middle` 第 #3 参数可选，但必须是字符串')
    local t = string.split(str, sep1)
    if not sep2 or sep1==sep2 then
        return t[2]
    else
        if t[2] == nil then
            return nil
        else
            t = string.split(t[2], sep2)
            if t[2] == nil then
                return nil
            else
                return t[1]
            end
        end
    end
end
-- 以上封装可复制到脚本中用
--
r = str_middle('您好，验证码是4937，15分钟内有效。【爆炸科技】', '码是', '，15分')
sys.alert('验证码是：'..r)
-- 输出 "验证码是：4937"
--
r = str_middle('您好，验证码是#8346#，15分钟内有效。【爆炸科技】', '#')
sys.alert('验证码是：'..r)
-- 输出 "验证码是：8346"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 封装示例 2

```lua
-- 取绝对路径的文件名
function str_strip_dirname(path)
    local d = string.split(path, '/')
    return d[#d]
end

-- 取绝对路径的目录
function str_strip_filename(path)
    local d = string.split(path, '/')
    d[#d] = nil
    return table.concat(d, '/')
end

-- 剔除路径最后一部分的扩展名（后缀名）
function str_strip_extension(path)
    local d = string.split(path, '/')
    local fnt = string.split(d[#d], '.')
    d[#d] = fnt[1]
    return table.concat(d, '/')
end

-- 获取路径最后一部分的扩展名（后缀名）
function str_get_extension(path)
    local d = string.split(path, '/')
    local fnt = string.split(d[#d], '.')
    table.remove(fnt, 1)
    return table.concat(fnt, '.')
end

sys.alert(str_strip_dirname("/private/var/mobile/Media/1ferver/lua/scripts/1.lua.xxt"))
-- 输出 "1.lua.xxt"

sys.alert(str_strip_filename("/private/var/mobile/Media/1ferver/lua/scripts/1.lua.xxt"))
-- 输出 "/private/var/mobile/Media/1ferver/lua/scripts"

sys.alert(str_strip_extension("/private/var/mobile/Media/1ferver/lua/scripts/1.lua.xxt"))
-- 输出 "/private/var/mobile/Media/1ferver/lua/scripts/1"

sys.alert(str_get_extension("/private/var/mobile/Media/1ferver/lua/scripts/1.lua.xxt"))
-- 输出 "lua.xxt"

sys.alert(str_strip_extension(str_strip_dirname("/private/var/mobile/Media/1ferver/lua/scripts/1.lua.xxt")))
-- 输出 "1"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[table.concat](https://cloudwu.github.io/lua53doc/manual.html#pdf-table.concat)


## 可能相关的示例 (将中英混合的文本爆开成一个个的字符，仅支持 UTF8 编码文本)

```lua
-- 这不是使用 string.split 实现的例子
function text_explode(text)
    local ret = {}
    for p, c in utf8.codes(text) do
        ret[#ret + 1] = utf8.char(c)
    end
    return ret
end
--
local t = text_explode('你好，XXTouch')
sys.alert(table.concat(t, '/')) -- 输出 "你/好/，/X/X/T/o/u/c/h"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)、[table.concat](https://cloudwu.github.io/lua53doc/manual.html#pdf-table.concat)、[utf8.char](https://cloudwu.github.io/lua53doc/manual.html#pdf-utf8.char)、[utf8.codes](https://cloudwu.github.io/lua53doc/manual.html#pdf-utf8.codes)


## 更多示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [去除文本左边空白字符 (string.ltrim)](https://xxtouch.app/docs/handbook/ext-string/string.ltrim.md)
Path: handbook/ext-string/string.ltrim.md

# 去除文本左边空白字符 (string.ltrim)


## 声明

```lua
处理后文本 = string.ltrim(处理前文本)
```


## 参数

- 处理前文本
    文本型，需要去除左边空白字符的文本

## 返回值

- 处理后文本
    文本型，返回已经去除左边空白字符的文本


## 说明

> 去除文本左边空白字符
> 空白字符包括 `"\r"` `"\n"` `"\t"`


## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [去除文本右边空白字符 (string.rtrim)](https://xxtouch.app/docs/handbook/ext-string/string.rtrim.md)
Path: handbook/ext-string/string.rtrim.md

# 去除文本右边空白字符 (string.rtrim)


## 声明

```lua
处理后文本 = string.rtrim(处理前文本)
```


## 参数

- 处理前文本
    文本型，需要去除右边空白字符的文本

## 返回值

- 处理后文本
    文本型，返回已经去除右边空白字符的文本


## 说明

> 去除文本右边空白字符
> 空白字符包括 `"\r"` `"\n"` `"\t"`


## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [去除文本左右两边空白字符 (string.trim)](https://xxtouch.app/docs/handbook/ext-string/string.trim.md)
Path: handbook/ext-string/string.trim.md

# 去除文本左右两边空白字符 (string.trim)


## 声明

```lua
处理后文本 = string.trim(处理前文本)
```


## 参数

- 处理前文本
    文本型，需要去除左右两边空白字符的文本

## 返回值

- 处理后文本
    文本型，返回已经去除左右两边空白字符的文本


## 说明

> 去除文本左右两边空白字符
> 空白字符包括 `"\r"` `"\n"` `"\t"`


## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [去除文本中所有的空白字符 (string.atrim)](https://xxtouch.app/docs/handbook/ext-string/string.atrim.md)
Path: handbook/ext-string/string.atrim.md

# 去除文本中所有的空白字符 (string.atrim)


## 声明

```lua
处理后文本 = string.atrim(处理前文本)
```


## 参数

- 处理前文本
    文本型，需要去除所有的空白字符的文本

## 返回值

- 处理后文本
    文本型，返回已经去除所有的空白字符的文本


## 说明

> 去除文本所有的空白字符
> 空白字符包括 `"\r"` `"\n"` `"\t"`


## 示例

参考 [本章末尾的综合示例](/docs/handbook/ext-string/samples.md)

---

Source: [去除掉文本前的 UTF8-BOM (string.strip_utf8_bom)](https://xxtouch.app/docs/handbook/ext-string/string.strip_utf8_bom.md)
Path: handbook/ext-string/string.strip_utf8_bom.md

# 去除掉文本前的 UTF8-BOM (string.strip_utf8_bom)


## 声明

```lua
处理后文本 = string.strip_utf8_bom(处理前文本)
```


## 参数

- 处理前文本
    文本型，需要剔除掉 UTF8-BOM 字符的文本

## 返回值

- 处理后文本
    文本型，返回已经剔除掉 UTF8-BOM 字符的文本


## 说明

> UTF8-BOM 的表现形式是文档开头的三个看不见的字符 `"\xEF\xBB\xBF"`  (在 Lua 源码中，字符串中 `\x` 开头，后面跟两位 16 进制数表示以该数字编码的单个字节。例如：`\x58` 表示 `X` 这个字符，可打印字符部分参考[《ASCII 编码》](https://baike.baidu.com/item/ASCII/309296))


## 示例

```lua
txt = "\xEF\xBB\xBFXXTouch"
sys.alert(txt..', '..#txt) -- 输出 "XXTouch, 10"
--
txt = string.strip_utf8_bom(txt)
sys.alert(txt..', '..#txt) -- 输出 "XXTouch, 7"
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)


## 小知识

> UTF-8 **不需要** BOM，尽管 Unicode 标准允许在 UTF-8 中使用 BOM。
> 不含 BOM 的 UTF-8 才是标准形式；在 UTF-8 文件中放置 BOM 主要是微软的习惯（注：将带 BOM 的小端序 UTF-16 称作「Unicode」而不加详细说明，同样是微软的习惯）。
> BOM（byte order mark）是为 UTF-16 和 UTF-32 准备的，用于标记字节序（byte order）。微软在 UTF-8 中使用 BOM 是因为这样可以将 UTF-8 和 ASCII 等编码明确区分开，但此类文件在 Windows 之外的操作系统上可能会引发问题。更多资料可参考 [Wikipedia – Byte order mark](https://zh.wikipedia.org/wiki/%E4%BD%8D%E5%85%83%E7%B5%84%E9%A0%86%E5%BA%8F%E8%A8%98%E8%99%9F)。

---

Source: [生成随机字符串 (string.random)](https://xxtouch.app/docs/handbook/ext-string/string.random.md)
Path: handbook/ext-string/string.random.md

# 生成随机字符串 (string.random)


## 声明

```lua
随机字符串 = string.random(字符池 [, 生成字符个数, 每字符的字节数 ])
```


## 参数

- 字符池
    文本型，需要生成字符串的字典
- 生成字符个数
    整数型，可选参数，需要生成的随机字符串中的字符个数，默认 6
- 每字符的字节数
    整数型，可选参数，每个字符的长度，默认 1

## 返回值

- 随机字符串
    文本型，返回生成的随机字符串


## 说明

> 生成随机字符串，UTF-8 编码的中文每个字符的长度为 3


## 示例

```lua
rs = string.random("qwertyuiopasdfghjklzxcvbnm", 20, 1)
rs = string.random("一二三四五六七八九十", 20, 3)
```

---

Source: [比较两个版本号大小 (string.compare_version)](https://xxtouch.app/docs/handbook/ext-string/string.compare_version.md)
Path: handbook/ext-string/string.compare_version.md

# 比较两个版本号大小 (string.compare_version)


## 声明

```lua
比较结果 = string.compare_version(版本号甲, 版本号乙)
```


## 参数

- 版本号甲, 版本号乙
    文本型，需要比较大小的两个版本号

## 返回值

- 比较结果
    整数型，版本号甲大于版本号乙返回 1，版本号甲小于版本号乙返回 -1，版本号相等返回 0


## 说明

> 比较两个版本号字符串大小，遵守如下比较规则
> 使用点 `.` 或减号 `-` 或空格隔开的纯数字值
> 不同分隔符效果相等，多个分隔符连在一起被认为是一个分隔符
> 权值随分段从左至右逐步降低
> 遇到任何非法字符将截断不对比后面的内容
> 如果段数不等，则不够段数用 '0' 补齐对比
> 空字符串或非法串会被认为版本号是 '0'
> 例如 '1.1' 与 '1.1.0' 是相等的两个版本号
> 例如 '1.1' 与 '1.1-0' 是相等的两个版本号
> 例如 '1.1' 与 '1-1' 是相等的两个版本号
> 例如 '1.0' 与 '1 0' \(1 和 0 之间有个空格\) 是相等的两个版本号
> 例如 '1.0' 大于 '0.99999'
> 该函数可在 XUI 中使用


## 示例

```lua
-- "1.5" 和 "1.05" 和 "1.005" 是同一个版本
-- "1.5" 和 "1.50" 和 "1.500" 是三个不同的版本号
-- "1.11" 大于 "1.5"
-- "1.52" 等于 "1.52.0"
assert(string.compare_version("", "") == 0)
assert(string.compare_version("1", "") == 1)
assert(string.compare_version("", "1") == -1)
assert(string.compare_version("1", "1") == 0)
assert(string.compare_version("1.0", "1") == 0)
assert(string.compare_version("1", "1.0") == 0)
assert(string.compare_version("1.", "1") == 0)
assert(string.compare_version("1", "1.") == 0)
assert(string.compare_version("1.", "1.0") == 0)
assert(string.compare_version("1.0", "1.") == 0)
assert(string.compare_version("1.0", "1.0") == 0)
assert(string.compare_version("1.0.0", "1.0.0") == 0)
assert(string.compare_version("1.1", "1.0") == 1)
assert(string.compare_version("1.0", "1.1") == -1)
assert(string.compare_version("1.1", "1.10") == -1)
assert(string.compare_version("1.2", "1.11") == -1)
assert(string.compare_version("1.1", "1.1.1") == -1)
assert(string.compare_version("1.2", "1.1.1") == 1)
assert(string.compare_version("1.0", "0.99999") == 1)
assert(string.compare_version("1.10.1", "1.10") == 1)
assert(string.compare_version("1.2-4", "1.2-3") == 1)
assert(string.compare_version("1.2-3", "1.2.3") == 0)
assert(string.compare_version("1.2-4", "1.2.3.0") == 1)
assert(string.compare_version("1.2-4", "1.2.3.10") == 1)
assert(string.compare_version("1.2-4", "1.2.30.10") == -1)
assert(string.compare_version("1.2-3", "1.2.4") == -1)
assert(string.compare_version("2.2", "1.2") == 1)
assert(string.compare_version("2.2", "10.2") == -1)
assert(string.compare_version("2..2", "2.2") == 0)
assert(string.compare_version("2.2.x.3", "2.2") == 0)
assert(string.compare_version("x", "") == 0)
```

---

Source: [判断字符串起始于 (string.starts_with)](https://xxtouch.app/docs/handbook/ext-string/string.starts_with.md)
Path: handbook/ext-string/string.starts_with.md

# 判断字符串起始于 (string.starts_with)


## 声明

```lua
是否以该前缀起始 = string.starts_with(源字符串, 前缀[, 位置])
```


## 参数

- 源字符串
    字符串型
- 前缀
    字符串型
- 位置
    整数型，可选参数，指定开始搜索的位置，默认 1

## 返回值

- 是否以该前缀起始
    布尔型


## 说明

> 判断字符串 `源字符串` 是否以 `前缀` 开头
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.starts_with('Hello, XXTouch', 'Hello')) -- 输出 true
nLog(string.starts_with('Hello, XXTouch', 'ello', 2)) -- 输出 true
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [判断字符串结束于 (string.ends_with)](https://xxtouch.app/docs/handbook/ext-string/string.ends_with.md)
Path: handbook/ext-string/string.ends_with.md

# 判断字符串结束于 (string.ends_with)


## 声明

```lua
是否以该后缀结尾 = string.ends_with(源字符串, 后缀[, 长度])
```


## 参数

- 源字符串
    字符串型
- 后缀
    字符串型
- 长度
    整数型，可选参数，指定搜索的长度，默认为 `源字符串` 的长度

## 返回值

- 是否以该后缀结尾
    布尔型


## 说明

> 判断字符串 `源字符串` 是否以 `后缀` 结尾
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.ends_with('Hello, XXTouch', 'XXTouch')) -- 输出 true
nLog(string.ends_with('Hello, XXTouch', 'ello', 5)) -- 输出 true
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [左填充字符串 (string.lpad)](https://xxtouch.app/docs/handbook/ext-string/string.lpad.md)
Path: handbook/ext-string/string.lpad.md

# 左填充字符串 (string.lpad)


## 声明

```lua
填充后的字符串 = string.lpad(源字符串, 长度, 填充字符)
```


## 参数

- 源字符串
    字符串型
- 长度
    整数型，指定填充后的字符串长度
- 填充字符
    字符串型，可选参数，指定填充的字符，默认为空格

## 返回值

- 填充后的字符串
    字符串型


## 说明

> 左填充字符串 `源字符串`，使其长度达到 `长度`，不足的用 `填充字符` 填充
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.lpad('ff',   6, '0'))  -- 输出 0000ff
nLog(string.lpad('100',  6, '0'))  -- 输出 000100
nLog(string.lpad('1234', 6, '0'))  -- 输出 001234
nLog(string.lpad('123',  6, 'xy')) -- 输出 xyx123
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [右填充字符串 (string.rpad)](https://xxtouch.app/docs/handbook/ext-string/string.rpad.md)
Path: handbook/ext-string/string.rpad.md

# 右填充字符串 (string.rpad)


## 声明

```lua
填充后的字符串 = string.rpad(源字符串, 长度, 填充字符)
```


## 参数

- 源字符串
    字符串型
- 长度
    整数型，指定填充后的字符串长度
- 填充字符
    字符串型，可选参数，指定填充的字符，默认为空格

## 返回值

- 填充后的字符串
    字符串型


## 说明

> 右填充字符串 `源字符串`，使其长度达到 `长度`，不足的用 `填充字符` 填充
> **该函数在 20250313 以后版本方可使用**


## 示例

```lua
nLog(string.rpad('ff',   6, '0'))  -- 输出 ff0000
nLog(string.rpad('100',  6, '0'))  -- 输出 100000
nLog(string.rpad('1234', 6, '0'))  -- 输出 123400
nLog(string.rpad('123',  6, 'xy')) -- 输出 123xyx
```
**注**：上述代码中使用了非本章函数 [`nLog`](/docs/handbook/develop-helper/nLog.md)

---

Source: [扩展 string 示例代码](https://xxtouch.app/docs/handbook/ext-string/samples.md)
Path: handbook/ext-string/samples.md

# 扩展 string 示例代码


```lua
-- 哈希校验
local str = "sozereal"
sys.alert('"'..str..'" 的 16 进制编码为: <'..str:to_hex()..'>')
sys.alert('<'..str:to_hex()..'> 转换成明文为: "'..str:to_hex():from_hex()..'"')
sys.alert('"'..str..'" 的 MD5 值是: '..str:md5())
sys.alert('"'..str..'" 的 SHA1 值是: '..str:sha1())
local binstr = "\0\1\2\3\4\5"
sys.alert('<'..binstr:to_hex()..'> 的 MD5 值是: '..binstr:md5())
sys.alert('<'..binstr:to_hex()..'> 的 SHA1 值是: '..binstr:sha1())
--
-- 数据加/解密
local msg = "\5\4\3\2\1\0"
local key = "sozereal"
local emsg = msg:aes128_encrypt(key)
local emsgb64 = emsg:base64_encode()
sys.alert('二进制数据<'..msg:to_hex()..'> \n 使用 AES128 算法 密钥 "'..key..'" 加密 值是: <'..emsg:to_hex()..'> \n base64 串为 "'..emsgb64..'"')
local tmp = emsgb64:base64_decode()
msg = tmp:aes128_decrypt(key)
sys.alert('"'..emsgb64..'" base64 解码后的数据为 <'..tmp:to_hex()..'> \n使用 AES128 算法 密钥 "'..key..'" 解密 值是: <'..msg:to_hex()..'>')
--
-- 字符串小工具
str = "  哈哈,he he,1,3,6  "
new = str:split(",") --将字符串str按照 `,` 分割并返回一个表
sys.alert(new[2])
sys.alert(str:rtrim()) -- 结果 "  哈哈,he he,1,3,6" ,删除字符串尾部的空白字符
sys.alert(str:ltrim()) -- 结果 "哈哈,he he,1,3,6  " ,删除字符串首部的空白字符
sys.alert(str:trim()) -- 结果 "哈哈,he he,1,3,6"    ,删除字符串首尾的空白字符
sys.alert(str:atrim()) -- 结果 "哈哈,hehe,1,3,6"    ,删除字符串所有的空白字符
```
**注**：上述代码中使用了非本章函数 [`sys.alert`](/docs/handbook/sys/sys.alert.md)

---

Source: [OpenAPI 目录](https://xxtouch.app/docs/OpenAPI/index.md)
Path: OpenAPI/README.md

# OpenAPI 目录

- [开始之前](START.md)
- [示例](Demo/README.md)
- [文件相关](FileSystem/README.md)
    - [获取文件列表](FileSystem/file_list.md)
    - [选择一个脚本文件](FileSystem/select_script_file.md)
    - [获取当前已经选择的脚本文件](FileSystem/get_selected_script_file.md)
    - [运行脚本文件](FileSystem/launch_script_file.md)
    - [新建一个目录](FileSystem/mkdir.md)
    - [删除一个目录](FileSystem/rmdir.md)
    - [重命名一个文件或目录（RAW）](FileSystem/rename_file.md)
    - [删除一个文件或空目录（RAW）](FileSystem/remove_file.md)
    - [读取一个文件（RAW）](FileSystem/read_file.md)
    - [写入一个文件（RAW）](FileSystem/write_file.md)
    - [跳转下载一个文件](FileSystem/download_file.md)
- [状态相关](Status/README.md)
    - [对明文脚本内容进行语法检测](Status/check_syntax.md)
    - [获得脚本运行状态](Status/is_running.md)
    - [获得前台应用画面旋转方向](Status/device_front_orien.md)
- [设置相关](Config/README.md)
    - [获取录制设置](Config/get_record_conf.md)
    - [录制设置开关](Config/set_record_conf.md)
    - [获取音量键事件设置](Config/get_volume_action_conf.md)
    - [音量键事件设置开关](Config/set_volume_action_conf.md)
    - [获取开机启动设置](Config/get_startup_conf.md)
    - [开机启动设置开关](Config/set_startup_conf.md)
    - [选择开机启动脚本](Config/select_startup_script_file.md)
    - [获得用户偏好配置](Config/get_user_conf.md)
    - [设置用户偏好配置](Config/set_user_conf.md)
    - [禁弹出 “无 SIM 卡” 弹窗开关](Config/set_no_nosim_alert.md)
    - [禁弹出 “低电量” 弹窗开关](Config/set_no_low_power_alert.md)
    - [禁弹出 “使用推送通知来连接 iTunes” 弹窗开关](Config/set_no_need_pushid_alert.md)
    - [设置设备名](Config/set_device_name.md)
    - [设置设备的屏幕背光度](Config/set_brightness.md)
    - [设置设备全局音量](Config/set_volume.md)
- [系统相关](System/README.md)
    - [获取设备已安装应用程序信息](System/applist.md)
    - [获取设备信息](System/deviceinfo.md)
    - [锁定屏幕](System/lock_screen.md)
    - [解锁屏幕](System/unlock_screen.md)
    - [重启服务](System/restart.md)
    - [注销设备](System/respring.md)
    - [重启设备](System/reboot2.md)
    - [关机](System/halt.md)
    - [清理 UI 缓存](System/uicache.md)
    - [全清设备](System/clear_all.md)
    - [清理应用程序存档](System/clear_app_data.md)
    - [导入一张照片到系统相册](System/image_to_album.md)
    - [更新自己](System/update_deb.md)
    - [打开远程访问](System/open_remote_access.md)
    - [关闭远程访问](System/close_remote_access.md)
    - [获取远程服务开启状态](System/is_remote_access_opened.md)
- [加密脚本相关](Encrypt/README.md)
    - [加密一个设备上的脚本文件](Encrypt/encript_file.md)
    - [加密一段明文脚本](Encrypt/encript.md)
    - [加密一段明文脚本并返回下载 URI](Encrypt/encript_2.md)
- [授权相关](License/README.md)
    - [绑定一个授权码](License/bind_code.md)
    - [获得当前设备的授权信息](License/device_auth_info.md)
- [控制相关](Control/README.md)
    - [UDP 扫描局域网的设备](Control/udp_scan.md)
    - [远程启动脚本接口](Control/spawn.md)
    - [停止脚本接口](Control/stop_script.md)
    - [暂停脚本接口](Control/pause_script.md)
    - [继续脚本接口](Control/resume_script.md)
    - [远程截图接口](Control/snapshot.md)
    - [设置进程词典条目的值](Control/proc_put.md)
    - [查看进程词典条目的值](Control/proc_get.md)
    - [推入条目到进程词典队列](Control/proc_queue_push.md)
    - [从进程词典队列弹出条目](Control/proc_queue_pop.md)
    - [弹出进程词典队列所有条目](Control/proc_queue_clear.md)

---

Source: [示例](https://xxtouch.app/docs/OpenAPI/Demo/index.md)
Path: OpenAPI/Demo/README.md

# 示例

- [XXT 局域网控制器简易示例[aardio 版]-0.0.0.57.zip-12.3kB](/zip/XXT%E5%B1%80%E5%9F%9F%E7%BD%91%E6%8E%A7%E5%88%B6%E5%99%A8%E7%AE%80%E6%98%93%E7%A4%BA%E4%BE%8B%5Baardio%E7%89%88%5D-0.0.0.57.zip)
- 注：[aardio](https://www.aardio.com/) 是一款 Windows 端的快速开发工具

---

Source: [文件相关](https://xxtouch.app/docs/OpenAPI/FileSystem/index.md)
Path: OpenAPI/FileSystem/README.md

# 文件相关

- [获取文件列表](file_list.md)
- [选择一个脚本文件](select_script_file.md)
- [获取当前已经选择的脚本文件](get_selected_script_file.md)
- [运行脚本文件](launch_script_file.md)
- [检查加密的脚本](api-check_xxt.md)
- [新建一个目录](mkdir.md)
- [删除一个目录](rmdir.md)
- [重命名一个文件或目录（RAW）](rename_file.md)
- [删除一个文件或空目录（RAW）](remove_file.md)
- [读取一个文件（RAW）](read_file.md)
- [写入一个文件（RAW）](write_file.md)
- [跳转下载一个文件](download_file.md)

---

Source: [状态相关](https://xxtouch.app/docs/OpenAPI/Status/index.md)
Path: OpenAPI/Status/README.md

# 状态相关

- [对明文脚本内容进行语法检测](check_syntax.md)
- [获得脚本运行状态](is_running.md)
- [获得前台应用画面旋转方向](device_front_orien.md)

---

Source: [设置相关](https://xxtouch.app/docs/OpenAPI/Config/index.md)
Path: OpenAPI/Config/README.md

# 设置相关

- [获取录制设置](get_record_conf.md)
- [录制设置开关](set_record_conf.md)
- [获取音量键事件设置](get_volume_action_conf.md)
- [音量键事件设置开关](set_volume_action_conf.md)
- [获取开机启动设置](get_startup_conf.md)
- [开机启动设置开关](set_startup_conf.md)
- [选择开机启动脚本](select_startup_script_file.md)
- [获得用户偏好配置](get_user_conf.md)
- [设置用户偏好配置](set_user_conf.md)
- [禁弹出 “无 SIM 卡” 弹窗开关](set_no_nosim_alert.md)
- [禁弹出 “低电量” 弹窗开关](set_no_low_power_alert.md)
- [禁弹出 “使用推送通知来连接 iTunes” 弹窗开关](set_no_need_pushid_alert.md)
- [设置设备名](set_device_name.md)
- [设置设备的屏幕背光度](set_brightness.md)
- [设置设备全局音量](set_volume.md)

---

Source: [系统相关](https://xxtouch.app/docs/OpenAPI/System/index.md)
Path: OpenAPI/System/README.md

# 系统相关

- [获取设备已安装应用程序信息](applist.md)
- [获取设备信息](deviceinfo.md)
- [锁定屏幕](lock_screen.md)
- [解锁屏幕](unlock_screen.md)
- [重启服务](restart.md)
- [注销设备](respring.md)
- [重启设备](reboot2.md)
- [关机](halt.md)
- [清理 UI 缓存](uicache.md)
- [全清设备](clear_all.md)
- [清理应用程序存档](clear_app_data.md)
- [导入一张照片到系统相册](image_to_album.md)
- [更新自己](update_deb.md)
- [打开远程访问](open_remote_access.md)
- [关闭远程访问](close_remote_access.md)
- [获取远程服务开启状态](is_remote_access_opened.md)

---

Source: [加密脚本相关](https://xxtouch.app/docs/OpenAPI/Encrypt/index.md)
Path: OpenAPI/Encrypt/README.md

# 加密脚本相关

- [加密一个设备上的脚本文件](encript_file.md)
- [加密一段明文脚本](encript.md)
- [加密一段明文脚本并返回下载 URI](encript_2.md)

---

Source: [授权相关](https://xxtouch.app/docs/OpenAPI/License/index.md)
Path: OpenAPI/License/README.md

# 授权相关

- [绑定一个授权码](bind_code.md)
- [获得当前设备的授权信息](device_auth_info.md)

---

Source: [控制相关](https://xxtouch.app/docs/OpenAPI/Control/index.md)
Path: OpenAPI/Control/README.md

# 控制相关

- [UDP 扫描局域网的设备](udp_scan.md)
- [远程启动脚本接口](spawn.md)
- [停止脚本接口](stop_script.md)
- [暂停脚本接口](pause_script.md)
- [继续脚本接口](resume_script.md)
- [远程截图接口](snapshot.md)
- [设置进程词典条目的值](proc_put.md)
- [查看进程词典条目的值](proc_get.md)
- [推入条目到进程词典队列](proc_queue_push.md)
- [从进程词典队列弹出条目](proc_queue_pop.md)
- [弹出进程词典队列所有条目](proc_queue_clear.md)

---

Source: [获取录制设置](https://xxtouch.app/docs/OpenAPI/Config/get_record_conf.md)
Path: OpenAPI/Config/get_record_conf.md

# 获取录制设置

- 接口描述

    ```http
    POST /get_record_conf HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "record_volume_up":true,  // 录制是否也包括音量上键
            "record_volume_down":true // 录制是否也包括音量下键
        }
    }
    ```

---

Source: [UDP 扫描局域网的设备](https://xxtouch.app/docs/OpenAPI/Control/udp_scan.md)
Path: OpenAPI/Control/udp_scan.md

# UDP 扫描局域网的设备

- 首先需要在电脑上打开一个 UDP 收消息的端口

- 然后发送如下 UDP 广播内容到局域网的 46953 端口

    ```json
    {"ip":"电脑端的 ip 地址","port":50000} // port 为电脑端的监听端口
    ```

- 设备收到这个广播后会做出如下回复到电脑的收消息端口

    ```json
    {
        "ip":"192.168.31.99",
        "port":"46952",
        "devname":"设备名",
        "deviceid":"123456789012345678901234567890123456790", // 设备 UDID
        "devsn":"XXXXXXXXXXXX",                               // 设备序列号
        "devmac":"02:03:04:05:06:07",                         // 设备 WiFi MAC 地址
        "devtype":"iPhone8,1",                                // 设备型号
        "zeversion":"0.0.1.738",                              // 服务版本
        "sysversion":"9.0.2"                                  // 系统版本
    }
    ```

- 电脑端 UDP 扫描局域网设备示例（适用于 Python 3.x）：

    ```python
    # -*- coding: utf-8 -*-
    import socket
    import json

    local_ip = '192.168.31.13'  # 电脑端地址
    local_port = 31500

    local = (local_ip, local_port)
    remote = ("255.255.255.255", 46953)
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    s.bind(local)

    s.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
    s.sendto(json.dumps({"ip": local_ip, "port": local_port}).encode('utf-8'), remote)  # 编码为 UTF-8

    while True:
        data, addr = s.recvfrom(2048)
        if not data:
            print("client has exited")  # 使用 print() 函数
            break
        print("received:", data, "from", addr)  # 使用 print() 函数

    s.close()
    ```

- 电脑端 UDP 扫描局域网设备示例（适用于 Node.js）：

    ```javascript
    var http = require('http');            //HTTP 服务

    var dgram = require('dgram');        //UDP 模块
    var server_Port = 31500;            //服务端口
    var client_Port = 31501;            //发信端口

    var device_List = {};                //设备列表

    //创建收信服务
    var server_Socket = dgram.createSocket('udp4');
    server_Socket.on('message', function(msg, rinfo){
        console.log('收到消息：%s', msg);
        var device_Info = JSON.parse(msg)
        //过滤重复
        if(device_Info.deviceid){
            device_List[device_Info.deviceid] = device_Info;
        }
    });
    server_Socket.bind(server_Port);

    //创建发信服务
    var client_Socket = dgram.createSocket('udp4');
    client_Socket.bind(client_Port);

    var search = function(){
        var server_List = new Array();
        var os = require('os');
        var ifaces = os.networkInterfaces();
        for (var dev in ifaces) {
            var alias = 0;
            ifaces[dev].forEach(function(details){
                if (details.family=='IPv4') {
                    server_List.push(details.address);
                    ++alias;
                }
            });
        };
        for(var address in server_List) {
            var ip_ar = server_List[address].split(".");
            var send2ip = ip_ar[0] + "." + ip_ar[1] + "." + ip_ar[2] + ".255";
            var client_Socket = dgram.createSocket('udp4');
            var msg = JSON.stringify({ip: server_List[address], port: server_Port});
            client_Socket.send(msg, 0, msg.length, 46953, send2ip);
        };
    }

    http.createServer(function (request, response) {
        response.writeHead(200, {'Content-Type': 'application/json'});
        search()
        response.end(
            JSON.stringify(device_List)
        );
    }).listen(22222);
    search()
    console.log('Web 服务地址：http://127.0.0.1:22222/');
    ```

---

Source: [加密一个设备上的脚本文件](https://xxtouch.app/docs/OpenAPI/Encrypt/encript_file.md)
Path: OpenAPI/Encrypt/encript_file.md

# 加密一个设备上的脚本文件

- 接口描述

    ```http
    POST /encript_file HTTP/1.1

    {
        "no_strip": true|false,             // 是否保留调试信息，默认 false，也就是不保留调试信息
        "in_file": "lua/scripts/xxx.lua",   // 输入文件名，可以为绝对路径
        "out_file": "lua/scripts/xxx.xxt",  // 输出文件名，可以为绝对路径
        "info": {},                         // 脚本包含的信息
        "entitlements": {
            "allow-external-require": true|false
        }
    }
    ```

- 参数说明

    - `no_strip`: `boolean`
        当该参数为 true 时，保留调试信息加密（即报错时会包含行号信息）。默认为 false
    - `in_file`: `string`
        需要加密的脚本文件路径，允许使用绝对路径或相对 `/var/mobile/Media/1ferver/` 的路径
    - `out_file`: `string`
        加密完成后输出的脚本文件路径，允许使用绝对路径或相对 `/var/mobile/Media/1ferver/` 的路径
    - `info`: `table`
        脚本包含的附加信息，通常包含脚本名称（Name）、版本（Version）、描述（Description）等字段
    - `entitlements`: `table`
        脚本权限信息
        - `allow-external-require` 字段
            若没有该字段或该字段为 false，则该脚本仅允许被当前作者证书加密的脚本所 require；该字段为列表时，允许列表中的证书作者脚本 require；该字段为 true 时，允许任意脚本 require

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
    ```
    ```json
    {"code":4,"message":"文件或目录不存在"} // 输入文件无法被读取
    ```
    ```json
    {"code":4,"message":"无法写入文件"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```
    ```json
    {"code":13,"message":"另外一项加密正在进行..."}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`

---

Source: [获取文件列表](https://xxtouch.app/docs/OpenAPI/FileSystem/file_list.md)
Path: OpenAPI/FileSystem/file_list.md

# 获取文件列表

- 接口描述

    ```http
    POST /file_list HTTP/1.1

    {"directory":"/lua/scripts/"}
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "list":[
                {
                    "name":"文件名",
                    "change":1446566100,
                    "size":144,
                    "access":1442128726,
                    "gid":20,
                    "blksize":4096,
                    "uid":0,
                    "rdev":0,
                    "blocks":8,
                    "nlink":1,
                    "permissions":"rw-r--r--",
                    "mode":"file",
                    "dev":16777219,
                    "ino":4887321,
                    "modification":1443063784
                },
                {
                    "name":"文件夹名",
                    "change":1464135126,
                    "size":102,
                    "access":1464135114,
                    "gid":20,
                    "blksize":4096,
                    "uid":0,
                    "rdev":0,
                    "blocks":0,
                    "nlink":2,
                    "permissions":"rwxr-xr-x",
                    "mode":"directory",
                    "dev":16777219,
                    "ino":9407305,
                    "modification":1464135126
                },
                ...
            ]
        }
    }
    ```

- 通过接口获取脚本列表 Python 3.x 示例（需要 requests）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    resp = requests.post(
        "http://192.168.31.72:46952/file_list",
        json={"directory": "/lua/scripts/"},
        timeout=30,
    )

    if resp.status_code == 200:
        ret = resp.json()
        if ret.get("code") == 0:
            for finfo in ret["data"]["list"]:
                name = finfo.get("name")
                if name not in (".", ".."):
                    print(name)
        else:
            print(ret.get("message"))
    else:
        print(resp.status_code, resp.reason)
        print(resp.text)
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`
    - 开源脚本模块存放目录为 `/var/mobile/Media/1ferver/lua/`
    - 脚本存放目录为 `/var/mobile/Media/1ferver/lua/scripts/`
    - 插件存放目录为 `/var/mobile/Media/1ferver/lib/`
    - 资源存放目录为 `/var/mobile/Media/1ferver/res/`
    - 日志存放目录为 `/var/mobile/Media/1ferver/log/`
    - UI 配置存放目录为 `/var/mobile/Media/1ferver/uicfg/`
    - 文字识别字库存放目录为 `/var/mobile/Media/1ferver/tessdata/`

---

Source: [绑定一个授权码](https://xxtouch.app/docs/OpenAPI/License/bind_code.md)
Path: OpenAPI/License/bind_code.md

# 绑定一个授权码

- 接口描述

    ```http
    POST /bind_code HTTP/1.1

    XXXXXXXXXXXXXXXX
    ```

- 可能的返回

    ```json
    {"code":0,"message":"充值成功，新增授权时间 XX 天 XX 小时 XX 分钟"}       // 表示绑定成功
    ```
    ```json
    {"code":1,"message":"操作失败"} // 连接服务器失败
    ```
    ```json
    {"code":-1,"message":"..."}       // 其它任何非 0 值原因都用 message 描述
    ```

---

Source: [开始之前](https://xxtouch.app/docs/OpenAPI/START.md)
Path: OpenAPI/START.md

# 开始之前

XXTouch OpenAPI 是 XXTouch 服务端在设备上进行监听并执行传入命令的开放式接口。开发者可通过 OpenAPI 实现对 XXTouch 的远程控制，是集成中控、远程调试和上传文件到设备的便捷方式。

在使用之前，请完成以下准备：

- **开启远程服务**
    在设备端依次操作：`打开应用 → 更多 → 远程服务 → 打开`
    图文教程：[使用手册](/docs/ABC/index.md#如何打开远程接口)
- 远程服务协议：`HTTP/1.1`
- 默认端口：`46952`
- 除非另有说明：
    接口文本参数均使用 `UTF-8` 编码
    接口返回值为 `UTF-8` 编码的文本
    正常响应的 HTTP 状态码为 `200`
    未开启远程服务时，所有接口统一返回 HTTP 状态码 `400`

---

Source: [对明文脚本内容进行语法检测](https://xxtouch.app/docs/OpenAPI/Status/check_syntax.md)
Path: OpenAPI/Status/check_syntax.md

# 对明文脚本内容进行语法检测

- 接口描述

    ```http
    POST /check_syntax HTTP/1.1

    明文脚本内容
    ```

- 可能的返回

    ```json
    {"code":0,"message":"语法检测已通过"}
    ```
    ```json
    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
    ```

---

Source: [获取设备已安装应用程序信息](https://xxtouch.app/docs/OpenAPI/System/applist.md)
Path: OpenAPI/System/applist.md

# 获取设备已安装应用程序信息

- 接口描述

    ```http
    POST /applist HTTP/1.1

    {"no_icon": true|false}
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":[
            {
                "bid":"com.xxx.xxx.1",
                "name":"应用本地化名字",
                "bundle_path":"应用包路径",
                "data_path":"应用数据路径",
                "icon":"应用程序图标数据（base64 编码）"
            },
            {
                "bid":"com.xxx.xxx.2",
                "name":"应用本地化名字",
                "bundle_path":"应用包路径",
                "data_path":"应用数据路径",
                "icon":"应用程序图标数据（base64 编码）"
            },
        ]
    }
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 说明
    - no_icon 参数可选，用于获取除 icon 数据以外所有的信息

---

Source: [录制设置开关](https://xxtouch.app/docs/OpenAPI/Config/set_record_conf.md)
Path: OpenAPI/Config/set_record_conf.md

# 录制设置开关

- 接口描述

    设置录制包含音量加键
    ```http
    POST /set_record_volume_up_on HTTP/1.1
    ```
    设置录制不包含音量加键
    ```http
    POST /set_record_volume_up_off HTTP/1.1
    ```
    设置录制包含音量减键
    ```http
    POST /set_record_volume_down_on HTTP/1.1
    ```
    设置录制不包含音量减键
    ```http
    POST /set_record_volume_down_off HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [远程启动脚本接口](https://xxtouch.app/docs/OpenAPI/Control/spawn.md)
Path: OpenAPI/Control/spawn.md

# 远程启动脚本接口

- 接口描述

    ```http
    POST /spawn HTTP/1.1
    spawn_args: {"脚本启动参数":...}

    [脚本正文]
    ```

- 可能的返回

    ```json
    {"code":1,"message":"操作失败"}
    ```
    ```json
    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
    ```
    ```json
    {"code":3,"message":"已经有脚本正在运行中"}
    ```
    ```json
    {"code":233,"message":"未知错误"}
    ```

- 说明
    - [脚本启动参数] 是一个不包含换行符的可打印字符串
    - [脚本正文] 是脚本内容，可以是文本也可以是加密的二进制数据
    - 脚本端可以通过 proc_get 或是 proc_take 获取脚本启动参数
    - 脚本将不会作为文件存到设备上，只是会运行
    - 上一条的例外，设备启用 脚本守护模式 的情况下，设备会缓存与设备相关的脚本数据


- 示例

    例如可以构造如下请求发送到设备
    ```http
    POST /spawn HTTP/1.1
    spawn_args: {"server_ip":"192.168.31.13","port":55555}
    Content-Length: 123

    local args = proc_get("spawn_args")
    args = json.decode(args)

    sys.alert("帐号服务器的 IP 为："..args.server_ip.."\n 端口为："..args.port)
    ```

    设备将会弹出一个提示框 ->
    ```
    账号服务器的 IP 为：192.168.31.13
    端口为：55555
    ```

    - 例子的 Python 语言实现（适用于 Python 3.x）：

    ```python
    # -*- coding: utf-8 -*-

    import http.client
    import json

    spawn_args = {
        "server_ip": "192.168.31.13",  # 电脑端 IP 地址
        "port": 55555,  # 电脑端端口
    }

    data = r'''
    local args = proc_get("spawn_args")
    args = json.decode(args)
    sys.alert("帐号服务器的 IP 为："..args.server_ip.."\n 端口为："..args.port)
    '''

    headers = {
        "Content-type": "text/lua",
        "spawn_args": json.dumps(spawn_args),
    }

    conn = http.client.HTTPConnection("192.168.31.72:46952")  # 设备端地址及端口
    conn.request("POST", "/spawn", data.encode('utf-8'), headers)  # 将 data 编码为 UTF-8

    response = conn.getresponse()
    print(response.status, response.reason)  # 使用 print() 函数

    data = response.read()
    print(data.decode('utf-8'))  # 解码响应数据并使用 print() 函数

    conn.close()
    ```

---

Source: [加密一段明文脚本](https://xxtouch.app/docs/OpenAPI/Encrypt/encript.md)
Path: OpenAPI/Encrypt/encript.md

# 加密一段明文脚本

- 接口描述

    ```http
    POST /encript HTTP/1.1
    args: {"no_strip":true|false, "info":{}, "entitlements":{}, "xuic":true|false}

    [脚本内容]
    ```

- 参数说明

    - `no_strip`: `boolean`
        当该参数为 true 时，保留调试信息加密（即报错时会包含行号信息）。默认为 false
    - `info`: `table`
        脚本包含的信息，通常包含脚本名称（Name）、版本（Version）、描述（Description）等字段
    - `entitlements`: `table`
        脚本权限信息
        - `allow-external-require` 字段
            若没有该字段或该字段为 false，则该脚本仅允许被当前作者证书加密的脚本所 require；该字段为列表时，允许列表中的证书作者脚本 require；该字段为 true 时，允许任意脚本 require
    - `xuic`: `boolean`
        当该参数为 true 时，会将一个 xui 文件加密为 xuic，其它参数会被忽略。默认为 false
    - `脚本内容`: `string`
        需要加密的脚本内容，作为请求体发送

- 可能的返回

    - 成功返回状态码 `200` 并附带内容：

        ```
        [加密好的脚本内容]
        ```

    - 失败返回状态码 `400` 并附带内容：

        ```json
        {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
        ```
        ```json
        {"code":13,"message":"另外一项加密正在进行..."}
        ```

---

Source: [选择一个脚本文件](https://xxtouch.app/docs/OpenAPI/FileSystem/select_script_file.md)
Path: OpenAPI/FileSystem/select_script_file.md

# 选择一个脚本文件

- 接口描述

    ```http
    POST /select_script_file HTTP/1.1

    {"filename":"文件名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```
    ```json
    {"code":4,"message":"无法读取文件"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 通过接口选择脚本文件 Python 3.x 示例（需要 requests）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    resp = requests.post(
        "http://192.168.31.72:46952/select_script_file",
        json={"filename": "123.lua"},
        timeout=30,
    )

    print(resp.status_code, resp.reason)  # 成功时 200 OK
    print(resp.json().get("message") if resp.status_code == 200 else resp.text)
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/lua/scripts/`

---

Source: [获得当前设备的授权信息](https://xxtouch.app/docs/OpenAPI/License/device_auth_info.md)
Path: OpenAPI/License/device_auth_info.md

# 获得当前设备的授权信息

- 接口描述

    ```http
    POST /device_auth_info HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"ok",
        "data":{
            "nowDate": 1517149407,
            "expireDate": 1517149407 // 过期时间 - 现在时间 小于等于 0 的话，也是过期
        }
    }
    ```
    ```json
    {"code":1,"message":"操作失败"}   // 连接服务器失败
    ```
    ```json
    {"code":-1,"message":"..."}         // 其它任何非 0 值原因都用 message 描述
    ```

---

Source: [获得脚本运行状态](https://xxtouch.app/docs/OpenAPI/Status/is_running.md)
Path: OpenAPI/Status/is_running.md

# 获得脚本运行状态

- 接口描述

    ```http
    POST /is_running HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"} // 代表没有脚本在运行也没有在录制
    ```
    ```json
    {"code":3,"message":"已经有脚本正在运行中"}
    ```
    ```json
    {"code":9,"message":"当前正在录制"}
    ```

---

Source: [获取设备信息](https://xxtouch.app/docs/OpenAPI/System/deviceinfo.md)
Path: OpenAPI/System/deviceinfo.md

# 获取设备信息

- 接口描述

    ```http
    POST /deviceinfo HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "devsn":"XXXXXXXXXXXX",                                // 设备序列号
            "zeversion":"0.0.1.733",                               // 服务程序版本
            "sysversion":"7.1.2",                                  // 系统版本
            "devname":"我的 iPhone",                                   // 设备名
            "devmac":"10:11:12:13:14:15",                          // 设备 MAC 地址
            "deviceid":"1234567890123456789012345678901234567890", // 设备 UDID
            "devtype":"iPhone5,3",                                 // 设备类型
            "wifi_ip":"192.168.1.100",                             // WIFI IP 地址
            "ipaddr":"127.0.0.1",                                  // 当前访问的本机地址
            "port":46952                                           // 端口
        }
    }
    ```

---

Source: [获取音量键事件设置](https://xxtouch.app/docs/OpenAPI/Config/get_volume_action_conf.md)
Path: OpenAPI/Config/get_volume_action_conf.md

# 获取音量键事件设置

- 接口描述

    ```http
    POST /get_volume_action_conf HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "hold_volume_up":"0", // 0 代表 “脚本启/停（有弹窗）”、1 代表 “脚本启/停”、2 代表 “无动作”；下同
            "hold_volume_down":"0",
            "click_volume_up":"0",
            "click_volume_down":"0",
            "activator_installed":true, // 是否安装了 Activator，如果安装了 Activator 则这里设置不生效
        }
    }
    ```

---

Source: [停止脚本接口](https://xxtouch.app/docs/OpenAPI/Control/stop_script.md)
Path: OpenAPI/Control/stop_script.md

# 停止脚本接口

- 接口描述

    ```http
    POST /stop_script HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"脚本即将停止"}
    ```

- 说明
    - 该接口返回时不保证脚本已完全停止，可通过 /is_running 接口检测

---

Source: [加密一段明文脚本并返回下载 URI](https://xxtouch.app/docs/OpenAPI/Encrypt/encript_2.md)
Path: OpenAPI/Encrypt/encript_2.md

# 加密一段明文脚本并返回下载 URI

- 接口描述

    ```http
    POST /encript HTTP/1.1
    args: {"no_strip":true|false, "info":{}, "entitlements":{}, "xuic":true|false, "filename":"UTF8-URIEncoded 文件名"}

    [脚本内容]
    ```

- 参数说明

    - `no_strip`: `boolean`
        当该参数为 true 时，保留调试信息加密（即报错时会包含行号信息）。默认为 false
    - `info`: `table`
        脚本包含的信息，通常包含脚本名称（Name）、版本（Version）、描述（Description）等字段
    - `entitlements`: `table`
        脚本权限信息
        - `allow-external-require` 字段
            若没有该字段或该字段为 false，则该脚本仅允许被当前作者证书加密的脚本所 require；该字段为列表时，允许列表中的证书作者脚本 require；该字段为 true 时，允许任意脚本 require
    - `xuic`: `boolean`
        当该参数为 true 时，会将一个 xui 文件加密为 xuic，其它参数会被忽略。默认为 false
    - `filename`: `string`
        下载链接返回时的文件名，需要提前进行 UTF-8 URI 编码
    - `脚本内容`: `string`
        需要加密的脚本内容，作为请求体发送

- 可能的返回

    - 成功返回状态码 `200` 并附带内容：

        ```json
        {
            "code":0,
            "message":"操作成功",
            "download_uri":"/download_encript", // 可以通过跳转到这个 URI 来下载加密好的文件
        }
        ```

    - 失败返回状态码 `400` 并附带内容：

        ```json
        {"code":2,"message":"操作失败"}
        ```
        ```json
        {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
        ```
        ```json
        {"code":13,"message":"另外一项加密正在进行..."}
        ```

---

Source: [获取当前已经选择的脚本文件](https://xxtouch.app/docs/OpenAPI/FileSystem/get_selected_script_file.md)
Path: OpenAPI/FileSystem/get_selected_script_file.md

# 获取当前已经选择的脚本文件

- 接口描述

    ```http
    POST /get_selected_script_file HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "filename":"当前选择的文件名"
        }
    }
    ```

- 通过接口获取已选择脚本 Python 3.x 示例（需要 requests）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    resp = requests.post("http://192.168.31.72:46952/get_selected_script_file", timeout=30)

    if resp.status_code == 200:
        ret = resp.json()
        print(ret.get("message"))
        if ret.get("code") == 0:
            print(ret["data"]["filename"])
    else:
        print(resp.status_code, resp.reason)
        print(resp.text)
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/lua/scripts/`

---

Source: [获得前台应用画面旋转方向](https://xxtouch.app/docs/OpenAPI/Status/device_front_orien.md)
Path: OpenAPI/Status/device_front_orien.md

# 获得前台应用画面旋转方向

- 接口描述

    ```http
    POST /device_front_orien HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","data":{"orien":0}} // 0 为 home 在下; 1 为 home 在右; 2 为 home 在左; 3 为 home 在上; 4 未知
    ```

---

Source: [锁定屏幕](https://xxtouch.app/docs/OpenAPI/System/lock_screen.md)
Path: OpenAPI/System/lock_screen.md

# 锁定屏幕

- 接口描述

    ```http
    POST /lock_screen HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [音量键事件设置开关](https://xxtouch.app/docs/OpenAPI/Config/set_volume_action_conf.md)
Path: OpenAPI/Config/set_volume_action_conf.md

# 音量键事件设置开关

- 接口描述

    设置长按音量加键的动作
    ```http
    POST /set_hold_volume_up_action HTTP/1.1

    0|1|2
    ```
    设置长按音量减键的动作
    ```http
    POST /set_hold_volume_down_action HTTP/1.1

    0|1|2
    ```
    设置按一下音量加键的动作
    ```http
    POST /set_click_volume_up_action HTTP/1.1

    0|1|2
    ```
    设置按一下音量减键的动作
    ```http
    POST /set_click_volume_down_action HTTP/1.1

    0|1|2
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [暂停脚本接口](https://xxtouch.app/docs/OpenAPI/Control/pause_script.md)
Path: OpenAPI/Control/pause_script.md

# 暂停脚本接口

- 接口描述

    ```http
    POST /pause_script HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

- 说明
    - 会在任何可能让出或等待时中断脚本，**强烈不建议使用此 API**
    - 重复调用不会产生额外效果
    - 按音量键弹出选择时会触发该 API，若需使用请注意避开冲突

---

Source: [运行脚本文件](https://xxtouch.app/docs/OpenAPI/FileSystem/launch_script_file.md)
Path: OpenAPI/FileSystem/launch_script_file.md

# 运行脚本文件

- 接口描述

    ```http
    POST /launch_script_file HTTP/1.1

    {"filename": "脚本文件名"}
    ```

- 说明
    `filename` 是可选参数，默认为当前已选择的脚本文件
    优先从 `/var/mobile/Media/1ferver/lua/scripts/` 下找，找不到则以绝对路径匹配


- 可能的返回

    ```json
    {"code":0,"message":"脚本运行开始"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```
    ```json
    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}
    ```
    ```json
    {"code":3,"message":"已有脚本正在运行中"}
    ```
    ```json
    {"code":4,"message":"无法读取文件"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```
    ```json
    {"code":9,"message":"脚本已损坏"}
    ```
    ```json
    {"code":10,"message":"软件需要更新方能支持使用这个脚本"}
    ```


- 通过接口运行已选择脚本 Python 3.x 示例（需要 requests）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    resp = requests.post("http://192.168.31.72:46952/launch_script_file", timeout=30)

    if resp.status_code == 200:
        print(resp.json().get("message"))
    else:
        print(resp.status_code, resp.reason)
        print(resp.text)
    ```

---

Source: [解锁屏幕](https://xxtouch.app/docs/OpenAPI/System/unlock_screen.md)
Path: OpenAPI/System/unlock_screen.md

# 解锁屏幕

- 接口描述

    ```http
    POST /unlock_screen HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [获取开机启动设置](https://xxtouch.app/docs/OpenAPI/Config/get_startup_conf.md)
Path: OpenAPI/Config/get_startup_conf.md

# 获取开机启动设置

- 接口描述

    ```http
    POST /get_startup_conf HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "startup_run":true, // true - 已启用开机启动；false - 未启用开机启动
            "startup_script":"开机启动的脚本名"
        }
    }
    ```
    ```json
    {"code":5,"message":"配置文件有误"}
    ```

---

Source: [继续脚本接口](https://xxtouch.app/docs/OpenAPI/Control/resume_script.md)
Path: OpenAPI/Control/resume_script.md

# 继续脚本接口

- 接口描述

    ```http
    POST /resume_script HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

- 说明
    - 调用暂停脚本接口后，可通过此 API 恢复执行，但**强烈不建议使用**
    - 重复调用不会产生额外效果
    - 该 API 会在音量键弹出选择后按取消时被调用，使用时请注意避免冲突

---

Source: [检查加密的脚本](https://xxtouch.app/docs/OpenAPI/FileSystem/api-check_xxt.md)
Path: OpenAPI/FileSystem/api-check_xxt.md

# 检查加密的脚本

- 接口描述

    ```http
    POST /api/check-xxt HTTP/1.1

    [XXT 脚本]
    ```

- 参数说明

    - `XXT 脚本`: `string` | `json`
        可以是需要检查的脚本的 RAW 内容，或如下所示的 JSON 文本：

        ```json
        {"filename": "设备上的 XXT 脚本文件名"}
        ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","data":{"info":"...","entitlements":"...","cert_info":{...}}}
    ```
    ```json
    {"code":4,"message":"无法读取文件"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 通过接口检查脚本 Python 3.x 示例（需要 requests）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    resp = requests.post(
        "http://192.168.11.115:46952/api/check-xxt",
        json={"filename": "/var/mobile/Media/1ferver/lua/scripts/1.xxt"},
        timeout=30,
    )

    if resp.status_code == 200:
        print("操作成功，内容：", resp.content)
    else:
        print("操作失败：", resp.status_code, resp.content)
    ```

---

Source: [重启服务](https://xxtouch.app/docs/OpenAPI/System/restart.md)
Path: OpenAPI/System/restart.md

# 重启服务

- 接口描述

    ```http
    POST /restart HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [开机启动设置开关](https://xxtouch.app/docs/OpenAPI/Config/set_startup_conf.md)
Path: OpenAPI/Config/set_startup_conf.md

# 开机启动设置开关

- 接口描述

    启用开机启动
    ```http
    POST /set_startup_run_on HTTP/1.1
    ```
    禁用开机启动
    ```http
    POST /set_startup_run_off HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"脚本运行的过程中无法做出该操作"}
    ```

---

Source: [远程截图接口](https://xxtouch.app/docs/OpenAPI/Control/snapshot.md)
Path: OpenAPI/Control/snapshot.md

# 远程截图接口

- 接口描述

    ```http
    GET /snapshot?ext=[扩展名]&compress=[压缩率]&orient=[旋转方向]&zoom=[缩放比例]&left=[左]&top=[上]&right=[右]&bottom=[下] HTTP/1.1
    ```

- 可能的返回

    ```图片数据```

- 说明
    - [扩展名] 可以是 png 或是 jpg
    - [压缩率] 范围 0~1，如果压缩率小于 1 则自动用 jpg 格式
    - [旋转方向] 范围 0~3；0 - 竖屏 home 在下；1 - 横屏 home 在右；2 - 横屏 home 在左；3 - 竖屏 home 在上
    - [缩放比例] 范围 0~3；默认 1；1.0.7-1 版以上有效
    - [左]、[上]、[右]、[下] 用于设定一个截图区域；区域无效则为全屏；1.0.7-1 版以上有效
```

---

Source: [注销设备](https://xxtouch.app/docs/OpenAPI/System/respring.md)
Path: OpenAPI/System/respring.md

# 注销设备

- 接口描述

    ```http
    POST /respring HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [选择开机启动脚本](https://xxtouch.app/docs/OpenAPI/Config/select_startup_script_file.md)
Path: OpenAPI/Config/select_startup_script_file.md

# 选择开机启动脚本

- 接口描述

    ```http
    POST /select_startup_script_file HTTP/1.1

    {"filename":"文件名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"脚本运行的过程中无法做出该操作"}
    ```

---

Source: [设置进程词典条目的值](https://xxtouch.app/docs/OpenAPI/Control/proc_put.md)
Path: OpenAPI/Control/proc_put.md

# 设置进程词典条目的值

- 接口描述

    ```http
    POST /proc_put HTTP/1.1

    {"key":"[键]","value":"[值]"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","key":"[键]","old_value":"[旧值]","value":"[新值]"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```

- 说明
    - 存储一个以 [键] 为键，值为 [值] 的条目到设备正在运行的 XXTouch 服务进程中
    - [键] 用于提取值
    - [值] 一个字符串


- 示例代码

    例如可以构造如下请求发送到设备
    ```http
    POST /proc_put HTTP/1.1
    Content-Length: 45

    {"key":"greeting","value":"Hello World"}
    ```

    然后设备的脚本中如果有如下代码
    ```lua
    sys.alert(proc_get("greeting"))
    ```

    设备将弹出一个提示框 ->
    ```
    Hello World
    ```

---

Source: [重启设备](https://xxtouch.app/docs/OpenAPI/System/reboot2.md)
Path: OpenAPI/System/reboot2.md

# 重启设备

- 接口描述

    ```http
    POST /reboot2 HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [获得用户偏好配置](https://xxtouch.app/docs/OpenAPI/Config/get_user_conf.md)
Path: OpenAPI/Config/get_user_conf.md

# 获得用户偏好配置

- 接口描述

    ```http
    POST /get_user_conf HTTP/1.1
    ```

- 可能的返回

    ```json
    {
        "code":0,
        "message":"操作成功",
        "data":{
            "no_nosim_alert":true|false,     // “无 SIM 卡” 弹窗设置，true 为不弹，默认 false
            "no_low_power_alert":true|false, // “低电量” 弹窗设置，true 为不弹，默认 false
            "no_idle":true|false,
            // 失眠模式，true 为不休眠，默认 false （该设置只在远程开启的情况下生效）
            "script_on_daemon":true|false,
            // 守护模式，true 表示服务异常退出后重启时会自动启动上次运行的脚本，默认 false
            "script_end_hint":true|false,    // 脚本停止提示文字开关，true 为提示，默认为 false
        }
    }
    ```

---

Source: [查看进程词典条目的值](https://xxtouch.app/docs/OpenAPI/Control/proc_get.md)
Path: OpenAPI/Control/proc_get.md

# 查看进程词典条目的值

- 接口描述

    ```http
    POST /proc_get HTTP/1.1

    {"key":"[键]"}
    ```

- 可能的返回

    ```json
    {"code":0,"key":"[键]","value":"[值]"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```

- 说明
    - 查看一个设备正在运行的 XXTouch 服务进程中以 [键] 为键的条目的值
    - 当设备正在运行的 XXTouch 服务进程中以 [键] 为键的条目没有值的时候，返回失败


- 示例代码

    例如当设备的脚本中执行如下代码
    ```lua
    proc_put("username", "test_user")
    ```

    然后构造如下请求发送到设备
    ```http
    POST /proc_get HTTP/1.1
    Content-Length: 18

    {"key":"username"}
    ```

    则会返回的数据如下
    ```json
    {"code":0,"key":"username","value":"test_user"}
    ```

---

Source: [新建一个目录](https://xxtouch.app/docs/OpenAPI/FileSystem/mkdir.md)
Path: OpenAPI/FileSystem/mkdir.md

# 新建一个目录

- 接口描述

    ```http
    POST /mkdir HTTP/1.1

    {"directory":"目录名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败","detail":"详细的错误信息"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`

---

Source: [关机](https://xxtouch.app/docs/OpenAPI/System/halt.md)
Path: OpenAPI/System/halt.md

# 关机

- 接口描述

    ```http
    POST /halt HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [设置用户偏好配置](https://xxtouch.app/docs/OpenAPI/Config/set_user_conf.md)
Path: OpenAPI/Config/set_user_conf.md

# 设置用户偏好配置

- 接口描述

    ```http
    POST /set_user_conf HTTP/1.1

    {
        "no_nosim_alert":true|false,     // “无 SIM 卡” 弹窗设置，true 为不弹，默认 false
        "no_low_power_alert":true|false, // “低电量” 弹窗设置，true 为不弹，默认 false
        "no_idle":true|false,
        // 失眠模式，true 为不休眠，默认 false （该设置只在远程开启的情况下生效）
        "script_on_daemon":true|false,
        // 守护模式，true 表示服务异常退出后重启时会自动启动上次运行的脚本，默认 false，无法在脚本运行的过程中打开此开关
        "script_end_hint":true|false,    // 脚本停止提示文字开关，true 为提示，默认为 false
    }
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"脚本运行的过程中无法做出该操作"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

---

Source: [推入条目到进程词典队列](https://xxtouch.app/docs/OpenAPI/Control/proc_queue_push.md)
Path: OpenAPI/Control/proc_queue_push.md

# 推入条目到进程词典队列

- 接口描述

    ```http
    POST /proc_queue_push HTTP/1.1

    {"key":"[键]","value":"[值]"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","size":10} // size 表示词典队列中的现存的条目数
    ```

- 说明
    - 压入一个以 [值] 为值的条目到键为 [键] 进程词典队列中
    - [键] 标识队列，用于从队列中提取值
    - [值] 一个字符串

---

Source: [删除一个目录](https://xxtouch.app/docs/OpenAPI/FileSystem/rmdir.md)
Path: OpenAPI/FileSystem/rmdir.md

# 删除一个目录

- 接口描述

    ```http
    POST /rmdir HTTP/1.1

    {"directory":"目录名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`
    - 该接口无条件删除目录，无论目录是否为空

---

Source: [清理 UI 缓存](https://xxtouch.app/docs/OpenAPI/System/uicache.md)
Path: OpenAPI/System/uicache.md

# 清理 UI 缓存

- 接口描述

    ```http
    POST /uicache HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [禁弹出 “无 SIM 卡” 弹窗开关](https://xxtouch.app/docs/OpenAPI/Config/set_no_nosim_alert.md)
Path: OpenAPI/Config/set_no_nosim_alert.md

# 禁弹出 “无 SIM 卡” 弹窗开关

- 接口描述

    禁止 “无 SIM 卡” 弹窗弹出
    ```http
    POST /set_no_nosim_alert_on HTTP/1.1
    ```
    不禁止 “无 SIM 卡” 弹窗弹出
    ```http
    POST /set_no_nosim_alert_off HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

- 说明
    - 该配置只在 iOS 12 及以下版本完整越狱环境有效

---

Source: [从进程词典队列弹出条目](https://xxtouch.app/docs/OpenAPI/Control/proc_queue_pop.md)
Path: OpenAPI/Control/proc_queue_pop.md

# 从进程词典队列弹出条目

- 接口描述

    ```http
    POST /proc_queue_pop HTTP/1.1

    {"key":"[键]"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","key":"[键]","value":"[值]"}
    ```

- 说明
    - 从进程词典队列中弹出一个值，如果队列为空，则会取出空字符串
    - [键] 标识队列，用于从队列中提取值

---

Source: [禁弹出 “低电量” 弹窗开关](https://xxtouch.app/docs/OpenAPI/Config/set_no_low_power_alert.md)
Path: OpenAPI/Config/set_no_low_power_alert.md

# 禁弹出 “低电量” 弹窗开关

- 接口描述

    禁止 “低电量” 弹窗弹出
    ```http
    POST /set_no_low_power_alert_on HTTP/1.1
    ```
    不禁止 “低电量” 弹窗弹出
    ```http
    POST /set_no_low_power_alert_off HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

- 说明
    - 该配置只在 iOS 12 及以下版本完整越狱环境有效

---

Source: [弹出进程词典队列所有条目](https://xxtouch.app/docs/OpenAPI/Control/proc_queue_clear.md)
Path: OpenAPI/Control/proc_queue_clear.md

# 弹出进程词典队列所有条目

- 接口描述

    ```http
    POST /proc_queue_clear HTTP/1.1

    {"key":"[键]"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","key":"[键]","values":["条目 1", "条目 2", ...]}
    ```

- 说明
    - 从进程词典队列弹出所有值
    - [键] 标识队列，用于从队列中提取值

---

Source: [重命名一个文件或目录（RAW）](https://xxtouch.app/docs/OpenAPI/FileSystem/rename_file.md)
Path: OpenAPI/FileSystem/rename_file.md

# 重命名一个文件或目录（RAW）

- 接口描述

    ```http
    POST /rename_file HTTP/1.1

    {"filename":"文件名","newfilename":"新文件名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败","detail":"具体的错误信息"}
    ```
    ```json
    {"code":4,"message":"文件或目录不存在"}
    ```
    ```json
    {"code":11,"message":"文件或目录已存在"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`

---

Source: [全清设备](https://xxtouch.app/docs/OpenAPI/System/clear_all.md)
Path: OpenAPI/System/clear_all.md

# 全清设备

- 接口描述

    ```http
    POST /clear_all HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"清理已经完成"}
    ```

---

Source: [禁弹出 “使用推送通知来连接 iTunes” 弹窗开关](https://xxtouch.app/docs/OpenAPI/Config/set_no_need_pushid_alert.md)
Path: OpenAPI/Config/set_no_need_pushid_alert.md

# 禁弹出 “使用推送通知来连接 iTunes” 弹窗开关

- 接口描述

    禁止 “使用推送通知来连接 iTunes” 弹窗弹出
    ```http
    POST /set_no_need_pushid_alert_on HTTP/1.1
    ```
    不禁止 “使用推送通知来连接 iTunes” 弹窗弹出
    ```http
    POST /set_no_need_pushid_alert_off HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

- 说明
    - 该配置只在 iOS 12 及以下版本完整越狱环境有效

---

Source: [删除一个文件或空目录（RAW）](https://xxtouch.app/docs/OpenAPI/FileSystem/remove_file.md)
Path: OpenAPI/FileSystem/remove_file.md

# 删除一个文件或空目录（RAW）

- 接口描述

    ```http
    POST /remove_file HTTP/1.1

    {"filename":"文件名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败","detail":"具体的错误信息"}
    ```
    ```json
    {"code":4,"message":"文件或目录不存在"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`

---

Source: [清理应用程序存档](https://xxtouch.app/docs/OpenAPI/System/clear_app_data.md)
Path: OpenAPI/System/clear_app_data.md

# 清理应用程序存档

- 接口描述

    ```http
    POST /clear_app_data HTTP/1.1

    {"bid":"应用包名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"清理已经完成"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```
    ```json
    {"code":11,"message":"这个应用程序的存档不能清理"}
    ```

---

Source: [设置设备名](https://xxtouch.app/docs/OpenAPI/Config/set_device_name.md)
Path: OpenAPI/Config/set_device_name.md

# 设置设备名

- 接口描述

    ```http
    POST /set_device_name HTTP/1.1

    {"name":"设备名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

---

Source: [读取一个文件（RAW）](https://xxtouch.app/docs/OpenAPI/FileSystem/read_file.md)
Path: OpenAPI/FileSystem/read_file.md

# 读取一个文件（RAW）

## 流式读取

- 接口描述

    ```http
    GET /read_file?filename=[URL 编码的文件名] HTTP/1.1
    ```

    - 可选查询参数 `md5=1`：在响应头添加 `Content-MD5`（Base64）

- 可能的返回

    - 成功：HTTP 200，响应体为文件内容字节流（非 base64 编码）
    - 失败：
        - HTTP 404 + `{"message":"File not found"}`（文件不存在或未传 filename）
        - HTTP 415 + `{"message":"File is a directory"}`（请求路径是目录）

- 通过接口流式读取设备脚本文件 Python 3.x 示例（需要 requests 模块）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    with requests.get(
        "http://192.168.31.72:46952/read_file",
        params={"filename": "lua/scripts/123.lua", "md5": 1},
        stream=True,
        timeout=30,
    ) as r:
        r.raise_for_status()
        with open("r:/123.lua", "wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                if chunk:
                    f.write(chunk)
            print("Content-MD5:", r.headers.get("Content-MD5"))
    ```


## Base64 读取

- 接口描述

    ```http
    POST /read_file HTTP/1.1

    {"filename":"文件名"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","data":"文件内容的 base64 编码字符串"}
    ```
    ```json
    {"code":4,"message":"无法读取文件"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

- 通过接口从设备读取脚本文件 Python 3.x 示例（需要 requests 模块）：

    ```python
    # -*- coding: utf-8 -*-
    import base64
    import requests

    resp = requests.post(
        "http://192.168.31.72:46952/read_file",
        json={"filename": "lua/scripts/123.lua"},
        timeout=30,
    )

    print(resp.status_code, resp.reason)  # 成功时 200 OK
    if resp.status_code == 200:
        ret = resp.json()
        print(ret.get("message"))
        if ret.get("code") == 0:
            print(base64.b64decode(ret["data"]).decode("utf-8"))  # 解码 base64 数据并显式解码为 UTF-8
    else:
        print(resp.text)
    ```

## 说明

- 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`
- [流式读取](#流式读取) 接口 `2025-07-11` 以后的版本可用

---

Source: [导入一张照片到系统相册](https://xxtouch.app/docs/OpenAPI/System/image_to_album.md)
Path: OpenAPI/System/image_to_album.md

# 导入一张照片到系统相册

- 接口描述

    ```http
    POST /image_to_album HTTP/1.1

    [图像数据]
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```

- 电脑端导入图片到设备相册示例（适用于 Python 3.x）：

    ```python
    # -*- coding: utf-8 -*-
    import http.client
    import json

    imgf = open('r:/1.png', 'rb')  # 图片文件路径
    imgdata = imgf.read()

    conn = http.client.HTTPConnection("192.168.31.72:46952")  # 设备端地址及端口
    conn.request("POST", "/image_to_album", imgdata)

    response = conn.getresponse()

    if response.status == 200:
        ret = json.loads(response.read().decode('utf-8'))  # 显式解码为 UTF-8
        print(ret['message'])
    else:
        print(response.status, response.reason)
        print(response.read().decode('utf-8'))  # 显式解码为 UTF-8

    conn.close()
    ```

- 说明
    - 支持的数据格式有 PNG、JPG

---

Source: [设置设备的屏幕背光度](https://xxtouch.app/docs/OpenAPI/Config/set_brightness.md)
Path: OpenAPI/Config/set_brightness.md

# 设置设备的屏幕背光度

- 接口描述

    ```http
    POST /set_brightness HTTP/1.1

    {"level":0.5}
    ```

    > `level` 取值范围为 0.0\~1.0

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

---

Source: [写入一个文件（RAW）](https://xxtouch.app/docs/OpenAPI/FileSystem/write_file.md)
Path: OpenAPI/FileSystem/write_file.md

# 写入一个文件（RAW）

## 流式写入

- 接口描述

    ```http
    PUT /write_file?filename=[URL 编码的文件名] HTTP/1.1

    [文件数据]
    ```

    - 直接接收文件字节流（非 base64 编码），适用于大文件上传
    - 若目标文件已存在会被覆盖

- 可能的返回

    - 成功：HTTP 204，无响应体
    - 失败：
        - HTTP 400 + `{"message":"invalid path"}`（未提供 filename 或路径非法）
        - HTTP 404 + `{"message":"invalid path"}`（无法创建目标路径）
        - HTTP 500 + `{"message":"…"}`

- 通过接口流式写入内容到设备脚本文件 Python 3.x 示例（需要 requests 模块）：

    ```python
    # -*- coding: utf-8 -*-
    import requests

    with open("r:/123.lua", "rb") as f:
        resp = requests.put("http://192.168.31.72:46952/write_file", params={"filename": "lua/scripts/123.lua"}, data=f, timeout=30)

    print(resp.status_code, resp.reason)  # 成功时 204 No Content
    if resp.status_code != 204:
        print(resp.text)
    ```


## Base64 写入

- 接口描述

    ```http
    POST /write_file HTTP/1.1

    {"filename":"文件名","data":"内容的 base64 编码字符串"}
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":4,"message":"无法写入文件"}
    ```

- 通过接口写入内容到设备脚本文件 Python 3.x 示例（需要 requests 模块）：

    ```python
    # -*- coding: utf-8 -*-
    import base64
    import requests

    with open('r:/123.lua', 'rb') as f:  # 脚本文件路径，直接读取字节
        resp = requests.post(
            "http://192.168.31.72:46952/write_file",
            json={
                "filename": "lua/scripts/123.lua",
                "data": base64.b64encode(f.read()).decode('utf-8')  # 直接对字节做 base64 编码
            },
            timeout=30,
        )

    print(resp.status_code, resp.reason)  # 成功时 200 OK
    print(resp.text)
    ```

## 说明

- 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`
- [流式写入](#流式写入) 接口 `2025-07-11` 以后的版本可用

---

Source: [更新自己](https://xxtouch.app/docs/OpenAPI/System/update_deb.md)
Path: OpenAPI/System/update_deb.md

# 更新自己

- 接口描述

    ```http
    POST /update_deb HTTP/1.1

    [deb 数据]
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```

- 说明
    - 该接口不会返回安装结果
    - 返回操作成功仅表示上传已完成，安装过程为异步执行
    - 该接口可能也支持安装其他 deb 包，但不提供兼容性保证
    - 巨魔版不能安装 deb，可以使用巨魔安装 tipa

---

Source: [设置设备全局音量](https://xxtouch.app/docs/OpenAPI/Config/set_volume.md)
Path: OpenAPI/Config/set_volume.md

# 设置设备全局音量

- 接口描述

    ```http
    POST /set_volume HTTP/1.1

    {"level":0.5}
    ```

    > `level` 取值范围为 0.0\~1.0

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":8,"message":"参数错误"}
    ```

---

Source: [跳转下载一个文件](https://xxtouch.app/docs/OpenAPI/FileSystem/download_file.md)
Path: OpenAPI/FileSystem/download_file.md

# 跳转下载一个文件

- 接口描述

    ```http
    GET /download_file?filename=[UTF8-URIEncoded 文件的路径]
    ```

- 可能的返回

    200
    ```
    [文件二进制内容]
    ```
    400
    ```json
    {"code":4,"message":"文件或目录不存在"}
    ```

- 说明
    - 该接口文件操作的根目录为 `/var/mobile/Media/1ferver/`
    - 该接口支持绝对路径，路径第一个字符是 / 则判定为绝对路径

---

Source: [打开远程访问](https://xxtouch.app/docs/OpenAPI/System/open_remote_access.md)
Path: OpenAPI/System/open_remote_access.md

# 打开远程访问

- 接口描述

    ```http
    POST /open_remote_access HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```
    ```json
    {"code":1,"message":"操作失败"}
    ```

- 说明
    - **该 API 仅限设备本机调用**

---

Source: [关闭远程访问](https://xxtouch.app/docs/OpenAPI/System/close_remote_access.md)
Path: OpenAPI/System/close_remote_access.md

# 关闭远程访问

- 接口描述

    ```http
    POST /close_remote_access HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功"}
    ```

---

Source: [获取远程服务开启状态](https://xxtouch.app/docs/OpenAPI/System/is_remote_access_opened.md)
Path: OpenAPI/System/is_remote_access_opened.md

# 获取远程服务开启状态

- 接口描述

    ```http
    POST /is_remote_access_opened HTTP/1.1
    ```

- 可能的返回

    ```json
    {"code":0,"message":"操作成功","data":{"opened":true|false}}
    ```

- 说明
    - **该 API 仅限设备本机调用**

---

Source: [XPP 脚本包](https://xxtouch.app/docs/XPP/index.md)
Path: XPP/README.md

# XPP 脚本包

在 XXTouch 1\.2 之前，我们以 Lua 作为开发语言，使用 `.lua` 作为**源代码**格式，`.xxt` 作为编译加密后的**可执行脚本**格式。然而，单一的源代码或可执行脚本往往需要引用模块、配置和资源文件，无法独立发布，也不便于打包、版本管理和资源调用。因此我们引入了 **XPP** 脚本包与 **XPA** 脚本包存档的概念。

---

- [XPP 格式](Layout)
    - [元信息](Layout/Info)
        - [BundleIdentifier (包标识符)](Layout/Info/BundleIdentifier.md)
        - [BundleVersion (脚本应用包的版本号)](Layout/Info/BundleVersion.md)
        - [BundleName (短名称)](Layout/Info/BundleName.md)
        - [BundleDisplayName (显示名称)](Layout/Info/BundleDisplayName.md)
        - [BundleIconFile (图标文件)](Layout/Info/BundleIconFile.md)
        - [Executable (可执行入口脚本文件)](Layout/Info/Executable.md)
        - [MainInterfaceFile (主界面配置入口文件)](Layout/Info/MainInterfaceFile.md)
        - [MinimumSystemVersion/MaximumSystemVersion (最低/最高 iOS 版本要求)](Layout/Info/SystemVersion.md)
        - [MinimumXXTVersion (最低 XXTouch 服务版本要求)](Layout/Info/MinimumXXTVersion.md)
        - [SupportedResolutions (支持的设备屏幕物理尺寸数组)](Layout/Info/SupportedResolutions.md)
        - [PackageControl (附加信息)](Layout/Info/PackageControl.md)
    - [本地化](Layout/Localizable.md)
- [XPA 打包格式](XPA.md)

---

Source: [元信息](https://xxtouch.app/docs/XPP/Layout/Info/index.md)
Path: XPP/Layout/Info/README.md

# 元信息

XPP 脚本包中需要一个名为 `Info.lua` 的脚本，返回一个用于描述当前脚本应用包元信息的 Lua 表常量。它通常不应该包含常量值以外的 Lua 代码。

以下是一个典型的 `Info.lua` 示例：

```lua
return {
    BundleIdentifier = "com.yourcompany.yourscript";
    BundleVersion = "0.0.1";
    BundleName = "Your Name";
    BundleDisplayName = "\U4f60\U7684\U540d\U5b57";
    BundleIconFile = "appicon.png";
    Executable = "xui-script.lua";
    MainInterfaceFile = "xui-demo.xui";
    MinimumSystemVersion = "10.0";
    MaximumSystemVersion = "10.2";
    MinimumXXTVersion = "1.1.2";
    SupportedResolutions = {
        {
            width = 640;
            height = 1136;
        };
    };
    PackageControl = {
        AuthorName = "i_82";
        AuthorEmail = "i.82@me.com";
        Description = "";
        Homepage = "https://82flex.com";
    };
};
```

`Info.lua` 返回的表通常包含以下键值对，各键值对的详细解释参见各子章节：

| 键 | 必选 | 建议 | 描述 |
|----|:---:|-----|------|
|BundleIdentifier|\*|\*|唯一标识符|
|BundleVersion|\*|\*|版本号|
|BundleName|\*|\*|名称|
|Executable||\*|可执行入口脚本文件名 ( **\.lua**, **\.xxt** ) |
|BundleDisplayName||\*|显示名称|
|BundleIconFile||\*|应用图标|
|MainInterfaceFile||\*|XUI 入口配置文件名 ( **\.xui**, **\.xuic** ) |
|MinimumSystemVersion|||最低系统版本要求|
|MaximumSystemVersion|||最高系统版本要求|
|MinimumXXTVersion|||最低 XXTouch 版本要求|
|SupportedResolutions|||设备分辨率支持数组|
|PackageControl|||附加信息|

*建议尽可能完善这些信息。完善的显示名称、应用图标和配置界面有助于提升脚本的整体观感与认可度。*

在脚本中，获取 `Info.lua` 中的常量信息，可通过 [XPP 脚本包模块](/docs/handbook/xpp/index.md) 获取。


**XPP 脚本包支持哪些脚本？**

XPP 脚本包支持的可执行脚本格式为 `.lua` 和 `.xxt`。脚本从脚本包中获取资源与配置，与单独运行并无显著区别。如需指定入口脚本，参见 Info.lua 的 [Executable](Executable.md) 字段。


**如何指定 XPP 的配置界面？**

如需指定 XPP 脚本包配置时的配置界面文件，参见 Info.lua 的 [MainInterfaceFile](MainInterfaceFile.md) 字段。如需编写配置界面 XUI 文件，参见 [XUI 界面库使用手册](/docs/XUI.md).


**如何处理 XPP 中的资源？**

- XPP 脚本包中的脚本/资源/模块/数据需放置于 XPP 目录中，通过相对路径访问。
- XPP 脚本包运行时所产生的临时文件/数据，请勿存放在 XPP 脚本包中，应存放于 XXTouch 缓存目录、临时目录等位置。

在脚本中，XPP 脚本包中的资源路径，可通过 [XPP 脚本包模块](/docs/handbook/xpp/index.md) 获取。

---

Source: [XPP 格式](https://xxtouch.app/docs/XPP/Layout/index.md)
Path: XPP/Layout/README.md

# XPP 格式

**XPP**（以下称“脚本应用包”）是可被 XXTouch 解析、查看与执行的一种 Bundle（包）结构，以单一文件的形式呈现给用户。这个“文件”实际上是一个以 **\.xpp** 为扩展名的目录，其结构如下：

| 文件 | 描述 |
|--------|--------|
|`Info.lua`|信息文件，结构化存储脚本应用包的配置。XXTouch 依据此文件识别 XPP 及其相关信息。|
|可执行脚本|每个脚本应用包必须包含至少一个可执行脚本（`.xxt` 或 `.lua`）。|
|界面配置|可选，可包含 XUI 配置文件（`.xui` 或 `.xuic`），为应用提供配置界面。|
|资源文件|可选，可执行脚本以外所需的数据文件。通常包括图像、图标、声音、本地化字符串、配置文件等。部分资源可针对特定语言或地区提供，亦可为通用资源。|

:::info 什么是 Bundle（包）？
Bundle 是一种特定结构、特定扩展名的目录，允许将相关资源（如可执行文件、本地化资源、图片等）组合为独立的项目。

多数类型的 Bundle 在使用时与普通文件无异，从而降低了内部文件被意外修改或丢失的风险。同时，Bundle 利用文件夹结构简化了资源组织方式，避免了使用资源分支带来的额外复杂性。
:::


![IMG_2723.jpg](XPPScreenshots/IMG_2723.jpg)

---

Source: [BundleDisplayName (显示名称)](https://xxtouch.app/docs/XPP/Layout/Info/BundleDisplayName.md)
Path: XPP/Layout/Info/BundleDisplayName.md

# BundleDisplayName (显示名称)

**显示名称**，该名称可以超过 16 个字符，仅用于显示在 XXTouch 应用程序中的脚本列表，不应该用于逻辑判断。

若不设置，则使用 **BundleName（短名称）** 的值。

---

Source: [BundleIconFile (图标文件)](https://xxtouch.app/docs/XPP/Layout/Info/BundleIconFile.md)
Path: XPP/Layout/Info/BundleIconFile.md

# BundleIconFile (图标文件)

**图标文件**，指定显示在 XXTouch 应用程序脚本列表中的图标，为脚本应用包中的相对路径。图标文件必须为 **\.png** 格式，若图标名为 **appicon.png**，则需提供以下图标：

| 文件名 | 尺寸 |
|--------|------|
|appicon.png|64 × 64|
|appicon@2x.png|128 × 128|
|appicon@3x.png|192 × 192|

若不设置，则显示默认图标。

---

Source: [BundleIdentifier (包标识符)](https://xxtouch.app/docs/XPP/Layout/Info/BundleIdentifier.md)
Path: XPP/Layout/Info/BundleIdentifier.md

# BundleIdentifier (包标识符)

**包标识符** 用来精确、唯一地表示一个独立脚本应用包。当开发者创建了一个脚本应用包并设置了 包标识符 后，该应用的 包标识符 在其整个生命周期内不能被更改。

包标识符 字符串必须为通用类型标识符（UTI），只允许包含数字与字母（A\-Z, a\-z, 0\-9）、短横线（\-）和点（\.）。该字符串通常应以倒序 DNS 格式呈现。例如，若开发者组织的域名为 82flex\.com，且脚本应用包名称为 Hello，则应以 com\.82flex\.hello 作为其 **包标识符**。

---

Source: [BundleName (短名称)](https://xxtouch.app/docs/XPP/Layout/Info/BundleName.md)
Path: XPP/Layout/Info/BundleName.md

# BundleName (短名称)

**短名称**，该名称不应超过 16 个字符，也可用于在脚本中显示和读取，用于菜单、推送。

---

Source: [BundleVersion (脚本应用包的版本号)](https://xxtouch.app/docs/XPP/Layout/Info/BundleVersion.md)
Path: XPP/Layout/Info/BundleVersion.md

# BundleVersion (脚本应用包的版本号)

**脚本应用包的版本号**，用于表示脚本应用包副本每一次的更新迭代，其格式为：

    1.1.0
    主版本.副版本.发布号

这种定义虽然并不严格，但值得注意的是，主版本、副版本、发布号均为整数，以点分隔，其中发布号可省略（默认为 0）：

    1.1
    主版本.副版本

在脚本应用包的生命周期中，每次发布版本号必须递增，其比较规则为：先比较主版本的数值，再比较副版本的数值，最后比较发布号的数值。

---

Source: [Executable (可执行入口脚本文件)](https://xxtouch.app/docs/XPP/Layout/Info/Executable.md)
Path: XPP/Layout/Info/Executable.md

# Executable (可执行入口脚本文件)

**可执行入口脚本文件**，指定直接运行将会执行的脚本文件在脚本应用包中的相对位置，必须为 **\.lua** 或 **\.xxt** 格式。

若不设置，该 XPP 不会显示启动按钮，且轻按时无法选中。若同时设置了 `MainInterfaceFile`，则轻按将进入配置界面，可从 XUI 配置界面中启动不同的入口脚本。

---

Source: [MainInterfaceFile (主界面配置入口文件)](https://xxtouch.app/docs/XPP/Layout/Info/MainInterfaceFile.md)
Path: XPP/Layout/Info/MainInterfaceFile.md

# MainInterfaceFile (主界面配置入口文件)

**主界面配置入口文件**，指定在 XXTouch 应用程序的脚本列表中选择配置脚本应用包时打开的 XUI 配置文件，必须为 **\.xui** 或 **\.xuic** 格式。**\.xuic** 是 **\.xui** 的加密格式，可在 App 中直接对 **\.xui** 文件进行加密。

若不设置，该 XPP 不显示配置按钮。

---

Source: [MinimumXXTVersion (最低 XXTouch 服务版本要求)](https://xxtouch.app/docs/XPP/Layout/Info/MinimumXXTVersion.md)
Path: XPP/Layout/Info/MinimumXXTVersion.md

# MinimumXXTVersion (最低 XXTouch 服务版本要求)

**最低 XXTouch 服务版本要求**，如不满足最低版本，则运行时提示不兼容的 XXTouch 版本。

若不设置，则默认兼容所有 XXTouch v1\.2\-1 及以上所有版本。

在 XXTouch 脚本中获取当前 XXTouch 版本：

    xver = sys.xtversion()

---

Source: [PackageControl (附加信息)](https://xxtouch.app/docs/XPP/Layout/Info/PackageControl.md)
Path: XPP/Layout/Info/PackageControl.md

# PackageControl (附加信息)

**附加信息**，字典类型。用于存放脚本应用包的作者信息、发布者信息、发布时间、版权信息等。支持的键值对如下：

| 键 | 说明 |
|----|------|
|AuthorName|作者名|
|AuthorEmail|作者电子邮件地址|
|Homepage|首页|
|Description|描述|
|Category|分类|
|Tags|标签|
|Copyright|版权信息|

这些信息将会在脚本包的项目属性以及安装时显示。

---

Source: [SupportedDeviceTypes (支持的设备类型数组)](https://xxtouch.app/docs/XPP/Layout/Info/SupportedDeviceTypes.md)
Path: XPP/Layout/Info/SupportedDeviceTypes.md

# SupportedDeviceTypes (支持的设备类型数组)

**支持的设备类型数组**。如运行设备的类型代号不在该数组中，则安装/配置/运行时提示不兼容的设备类型。

若不设置，则默认兼容所有的设备类型。

在 XXTouch 脚本中获取设备类型：

    dtype = device.type()

---

Source: [SupportedResolutions (支持的设备屏幕物理尺寸数组)](https://xxtouch.app/docs/XPP/Layout/Info/SupportedResolutions.md)
Path: XPP/Layout/Info/SupportedResolutions.md

# SupportedResolutions (支持的设备屏幕物理尺寸数组)

**支持的设备屏幕物理尺寸数组**。如运行设备的屏幕尺寸不在该数组中，则安装/配置/运行时提示不兼容的设备屏幕尺寸。

若不设置，则默认兼容所有设备屏幕尺寸。

在 XXTouch 脚本中获取设备屏幕物理尺寸：

    width, height = screen.size()

---

Source: [MinimumSystemVersion/MaximumSystemVersion (最低/最高 iOS 版本要求)](https://xxtouch.app/docs/XPP/Layout/Info/SystemVersion.md)
Path: XPP/Layout/Info/SystemVersion.md

# MinimumSystemVersion/MaximumSystemVersion (最低/最高 iOS 版本要求)

**最低/最高 iOS 版本要求**，如不在该区间，则安装/配置/运行时提示不兼容的 iOS 版本。

在 XXTouch 脚本中获取当前系统版本：

    ver = sys.version()

---

Source: [本地化](https://xxtouch.app/docs/XPP/Layout/Localizable.md)
Path: XPP/Layout/Localizable.md

# 本地化

XPP 脚本包支持元信息本地化和本地化资源调用。其策略与 [iOS 本地化](https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html) 保持一致——您可以将脚本包的 Info.plist 或 `.strings` 文件放置在多语言文件夹 `.lproj` 中，实现脚本包的多语言化。具体用法请参考 Apple 官方的 iOS 本地化文档。

---

Source: [XPA 打包格式](https://xxtouch.app/docs/XPP/XPA.md)
Path: XPP/XPA.md

# XPA 打包格式

XPP 脚本包目录可以打包为 XPA 格式进行分发。用户在客户端上安装后，会自动还原为 XPP 脚本包目录。

XPA 格式实质上是 `.zip` 压缩文件，其内部目录结构如下：

```
Demo.xpa (zipped)
    - Payload
        - A-Script-Bundle.xpp
```

只需将准备好的 `.xpp` 脚本包放置在 `Payload` 目录下，将 `Payload` 目录压缩为 `.zip` 文件，再将后缀名改为 `.xpa` 即可。

---

Source: [XUI 界面库目录](https://xxtouch.app/docs/XUI/index.md)
Path: XUI/README.md

# XUI 界面库目录

---

- [前言](START.md)
- [示例](Demo)
- [创建](Creation)
    - [根](Creation/Root.md)
    - [主题](Creation/Theme.md)
    - [通用属性](Creation/General.md)
    - [读取配置](Creation/ReadSettings.md)
- [组件](Modules/README.md)
    - [Group 分组](Modules/Group.md)
    - [Link 链接子界面](Modules/Link.md)
    - [Switch 开关](Modules/Switch.md)
    - [Button 动作按钮](Modules/Button.md)
    - [TextField 单行文本框](Modules/TextField.md)
    - [Radio / Checkbox 单选框 / 复选框组](Modules/Radio_Checkbox.md)
    - [Segment 适合少量选项的单项选择](Modules/Segment.md)
    - [Option 单项选择列表](Modules/Option.md)
    - [MultipleOption 多项选择列表](Modules/MultipleOption.md)
    - [OrderedOption 多项有序选择列表](Modules/OrderedOption.md)
    - [EditableList 可编辑列表](Modules/EditableList.md)
    - [Slider 数值拖拽滑块](Modules/Slider.md)
    - [Stepper 数值调节按钮](Modules/Stepper.md)
    - [DateTime 时间日期选择器](Modules/DateTime.md)
    - [TitleValue 键值对显示; 代码片段选择器](Modules/TitleValue.md)
    - [StaticText 静态文本框](Modules/StaticText.md)
    - [Textarea 多行文本域](Modules/Textarea.md)
    - [Image / AnimatedImage 图片 / 动态图片](Modules/Image_AnimatedImage.md)
    - [File 文件选择器](Modules/File.md)
    - [About 关于](Modules/About.md)
- [XUI 支持的 API](Internal_Lua_Module.md)
- [代码片段](Snippet/README.md)
    - [代码片段创建](Snippet/Creation.md)
    - [应用程序选择器](Snippet/app.md)
    - [虚拟按键选择器](Snippet/key.md)
    - [地理位置选择器](Snippet/loc.md)
    - [图像位置与颜色选择器](Snippet/poscolor.md)
    - [图像区域选择器](Snippet/rect.md)

---

Source: [示例](https://xxtouch.app/docs/XUI/Demo/index.md)
Path: XUI/Demo/README.md

# 示例

![XUI-Light.png](XUI-Light.png)

使用 XXTouch 扫码下载示例包。
![XUIDemoQRCode.png](XUIDemoQRCode.png)

---

Source: [创建](https://xxtouch.app/docs/XUI/Creation/index.md)
Path: XUI/Creation/README.md

# 创建

`.xui` 脚本是一种特定格式的 `.lua` 脚本（即以 UTF-8 编码的纯文本文件）。使用这种格式创建 XUI 界面，需要使 Lua 执行后返回一个包含各组件及属性的表。`.xui` 可通过 App 内置的加密功能加密为 `.xuic`，从而有效防止非法篡改。

尽管技术上可行，但不推荐使用 `.json` 或 `.plist` 格式来创建 XUI 界面。

---

Source: [组件](https://xxtouch.app/docs/XUI/Modules/index.md)
Path: XUI/Modules/README.md

# 组件

- [Group 分组](Group.md)
- [Link 链接子界面](Link.md)
- [Switch 开关](Switch.md)
- [Button 动作按钮](Button.md)
- [TextField 单行文本框](TextField.md)
- [Radio / Checkbox 单选框 / 复选框组](Radio_Checkbox.md)
- [Segment 适合少量选项的单项选择](Segment.md)
- [Option 单项选择列表](Option.md)
- [MultipleOption 多项选择列表](MultipleOption.md)
- [OrderedOption 多项有序选择列表](OrderedOption.md)
- [EditableList 可编辑列表](EditableList.md)
- [Slider 数值拖拽滑块](Slider.md)
- [Stepper 数值调节按钮](Stepper.md)
- [DateTime 时间日期选择器](DateTime.md)
- [TitleValue 键值对显示; 代码片段选择器](TitleValue.md)
- [StaticText 静态文本框](StaticText.md)
- [Textarea 多行文本域](Textarea.md)
- [Image / AnimatedImage 图片 / 动态图片](Image_AnimatedImage.md)
- [File 文件选择器](File.md)
- [About 关于](About.md)

---

Source: [代码片段](https://xxtouch.app/docs/XUI/Snippet/index.md)
Path: XUI/Snippet/README.md

# 代码片段

代码片段模板 `.snippet` 是一种特殊的 Lua 文件，用于描述如何将一个或多个「代码片段选择器」产生的结果组合为纯文本代码片段或其它对象。生成的对象可保存到 XUI 配置中；若为文本对象，还可快速插入代码编辑器。

「代码片段选择器」是一系列用于生成代码片段的预置选择器组件，支持以下类型：

- 单个应用程序选择器 `app`
- 多个应用程序选择器 `apps`
- 地理位置选择器 `loc`
- 虚拟按键选择器 `key`
- 单个图像位置选择器 `pos`
- 单个图像颜色选择器 `color`
- 单个图像位置与颜色选择器 `poscolor`
- 多个图像位置与颜色选择器 `poscolors`
- 图像区域选择器 `rect`

- [代码片段创建](Creation.md)
- [应用程序选择器](app.md)
- [虚拟按键选择器](key.md)
- [地理位置选择器](loc.md)
- [图像位置与颜色选择器](poscolor.md)
- [图像区域选择器](rect.md)

---

Source: [Group 分组](https://xxtouch.app/docs/XUI/Modules/Group.md)
Path: XUI/Modules/Group.md

# Group 分组

此组件在界面上显示一个分组区域，包含到下一个分组组件之间的所有组件。通常用于功能划分或对某一组件的补充描述。列表中的第一个组件必须是 `Group`；如果不是，XUI 会自动在列表首位添加一个 `Group` 组件。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|label|字符串|分组标题|可本地化|`""`|\-|
|footerText|字符串|在当前组之后添加一行小字|可本地化|`""`|\-|

此组件不支持 `icon`/`height`。


# 主题

|主题键|类型|描述|
|---|---|---|
|groupHeaderTextColor|*颜色*|分组首部标题颜色，即 `label` 的颜色|
|groupFooterTextColor|*颜色*|分组尾部文字颜色，即 `footerText` 的颜色|
|groupHeaderBackgroundColor|*颜色*|分组首部背景颜色|
|groupFooterBackgroundColor|*颜色*|分组尾部背景颜色|


## 示例

```lua
-- 分组组件
{
    cell = "Group";
    label = "开关";  -- 分组标题
    footerText = "这是一组开关";  -- 分组底部描述
};
-- 下面的两个组件是两个开关，会包含在该分组内
{
    default = true;
    label = "启用某功能";
    cell = "Switch";
    key = "enabled";  -- 该项存储的键，读取该键配置时需要用到
};
{
    default = false;
    label = "带图标的开关";
    cell = "Switch";
    key = "enabled1";  -- 该项存储的键，读取该键配置时需要用到
    icon = "res/16.png";  -- 其它有些组件也可以设置图标
    readonly = true; -- 所有组件都支持禁用
};
-- 另一分组
{
    cell = "Group";
    label = "另一组";
};
-- ...
```

![XUI-Group.png](XUIScreenshots/XUI-Group.png)

---

Source: [代码片段创建](https://xxtouch.app/docs/XUI/Snippet/Creation.md)
Path: XUI/Snippet/Creation.md

# 代码片段创建

## 创建

通常，「代码片段模板」`.snippet` 文件需要直接返回一个表，如：

```lua
return {
    name = '测试片段';  -- 代码片段名称
    description = '用于测试各选择器的功能';  -- 代码片段描述
    arguments = {  -- 代码片段选择器列表
        {  -- 选择器 1
            type = 'app',  -- 选择器类型
            title = '选择应用',  -- 选择器标题
            subtitle = '请选择一个应用',  -- 选择器副标题
            default = 'com.xxtouch.XXTExplorer',  -- 选择器默认值
        },
        {  -- 选择器 2
            type = 'loc',
            title = '选择地理位置',
            subtitle = '请随便选择一个地理位置',
            default = xui.get("com.darwindev.XXTExplorer", "location1"),
            -- 代码片段 .snippet 中可以使用 .xui 支持的所有 API
        },
        {  -- 选择器 3

        },
        -- ...
    };
    generator = function (...)  -- 可变参数生成器
        -- 处理参数并返回生成的结果
        local result
        return result
    end;
}
```


## 根层级

|键|类型|描述|
|---|---|---|
|name|字符串|代码片段名称|
|description|字符串|代码片段描述|
|arguments|数组|代码片段选择器列表|
|generator|函数|代码片段生成器|
|output|字符串|代码片段独立输出文件名|

`name` 和 `description` 分别为代码片段模板的显示名称与显示描述，会显示在文件管理器、代码片段的入口处。

`arguments` 为包含了一个或多个 **选择器参数字典** 的数组。App 将根据该数组中约定的选择器顺序，创建出一个选择器队列，依次让用户进行选择操作。用户完成选择器队列后，App 会将各选择器的返回值作为可变传入参数，依次传入生成器 `generator` 并调用它，最后将 `generator` 的返回值返回给调用方。

代码片段模板 `.snippet` 是可以独立使用的。如果需要允许它独立使用，可为其设置 `output` 字段，`generator` 生成的结果文本将保存到同一目录下 `output` 所标识的文件中。


## 选择器参数字典

|键|类型|描述|
|---|---|---|
|type|字符串|选择器类型|
|title|字符串|选择器标题，显示在选择器页面下方|
|subtitle|字符串|选择器副标题，显示在选择器页面下方|
|default|基本类型|选择器默认值|

有关各类型选择器 **选择器参数字典** 的详细介绍，参见后文内容。


## 在 XUI 中使用

如果代码片段模板 `.snippet` 在 XUI 的 [TitleValue](/docs/XUI/Modules/TitleValue.md) 组件中使用，即可从 XUI 中唤起选择器队列，并将结果保存到 XUI 组件的配置项中。同时该 `.snippet` 可调用 XUI 支持的所有 API，如 `xui.get`/`xui.set`/`xpp.bundle_path` 等。


## 在代码编辑器中使用

将代码片段模板 `.snippet` 放置到主目录的 `snippets` 目录中，即可被 App 的代码编辑器所调用。轻按键盘工具类右上角的星形按钮，即可快速生成代码片段，并插入到编辑的代码中。


## 作为独立文件使用

为代码片段模板 `.snippet` 设置 `output` 字段，并将代码片段放置在主目录的 `lua/scripts` 目录中，即可从 App 中直接点击，开始选择器队列，`generator` 生成的结果文本将保存到同一目录下 `output` 所标识的文件中。

---

Source: [前言](https://xxtouch.app/docs/XUI/START.md)
Path: XUI/START.md

# 前言

在阅读本文之前，您需要对 Lua 语法有所了解，并能理解数值、布尔型、字符串、表等基本数据类型。

- XUI 不与原有的对话框（dialog）和 WebView UI 冲突。
- XUI 为 [XPP 脚本包](/docs/XPP/index.md) 提供界面扩展。

XUI 用于在 XXTouch 上提供配置界面，基于 iOS 系统原生组件构建。本手册提供了 XUI 界面布局的完整规范。我们还提供了完整的 [XUI 示例脚本包](/docs/XUI/Demo/index.md)，建议结合示例阅读本手册的各章节内容。

XUI 是 [XPP 脚本包](/docs/XPP/index.md) 的一部分，用来为脚本包创建配置界面，不可独立使用。如需使用 XUI，请 [创建](/docs/XUI/Creation/index.md) 指定格式的 `.xui` 脚本，将其放置在 XPP 脚本包中，并在 `Info.lua` 中设置 `MainInterfaceFile` 字段。详情参见 [XPP 脚本包](/docs/XPP/index.md)。

配置项可通过 [XUI 脚本配置界面模块](/docs/handbook/xui/index.md) 进行读取、写入和更新。


![IMG_2722.jpg](XUIScreenshots/IMG_2722.jpg)

---

Source: [Link 链接子界面](https://xxtouch.app/docs/XUI/Modules/Link.md)
Path: XUI/Modules/Link.md

# Link 链接子界面

此组件在界面上显示一个子菜单项，通常用于链接子界面。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|url|字符串|子界面文件名|*|\-|\-|

`url` 可以为普通文件名、XUI 文件名或网络地址。普通文件将使用默认打开方式打开，xui/xuic 文件将作为子界面打开，网络地址将使用内置浏览器打开。


## 示例

```lua
{
    cell = "Group";
    label = "子页面";
};
{
    url = "sub/xui-sub.xuic"; -- 相对于 xpp 的路径
    cell = "Link";
    label = "更多组件演示";
};
{
    url = "sub/xui-dynamic.xui";
    cell = "Link";
    label = "动态联动通知演示";
};
{
    cell = "Group";
    label = "资源浏览";
};
{
    url = "https://xxtouch.app";
    cell = "Link";
    label = "打开 XXTouch.app";
};
{
    url = "res/b6d21727a66f856f79dc9b6ef8e7b4d6.gif";
    cell = "Link";
    label = "打开一个图片";
};
{
    url = "res/SmartSelect.mp4";
    cell = "Link";
    label = "打开一个视频";
};
{
    url = "https://www.apple.com/apple-events/september-2015/";
    cell = "Link";
    label = "在线视频";
};
```

![XUI-Link.png](XUIScreenshots/XUI-Link.png)

---

Source: [应用程序选择器](https://xxtouch.app/docs/XUI/Snippet/app.md)
Path: XUI/Snippet/app.md

# 应用程序选择器

「应用程序选择器」提供了一个应用程序预览列表，提供了允许用户选择一个或多个应用程序的能力。

类型为 `app` 的「单个应用程序选择器」只允许用户勾选一个应用程序，其返回值为 **字符串**，是用户所选应用程序的 Bundle ID。

而类型为 `apps` 的「多个应用程序选择器」允许用户拖选多个应用程序并为其排序，其返回值为 **包含字符串的数组**，是用户所选应用程序 Bundle ID 的有序集合。


## 示例

```lua
local group, name

group = 'App'
name = 'app.bundle_path(bid)'

return {
    name = string.format('%s - %s', group, name),
    description = "获取 App 的应用程序包路径",
    arguments = {
        {type = 'app'},
    },
    default = "com.darwindev.XXTExplorer",  -- 默认选中的应用 Bundle ID
    generator = function(bid)
        return string.format('app.bundle_path(%q)', bid)
    end,
}
```

![IMG_0005.PNG](XUIScreenshots/IMG_0005.PNG)

![IMG_0006.PNG](XUIScreenshots/IMG_0006.PNG)

---

Source: [Switch 开关](https://xxtouch.app/docs/XUI/Modules/Switch.md)
Path: XUI/Modules/Switch.md

# Switch 开关

此组件在界面上显示一个开关。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|negate|布尔型|反转开关显示情况|\-|`false`|\-|
|trueValue|基本类型|当结果为 `true` 时保存的值<br />若不填则保存 `true`|\-|`true`|\-|
|falseValue|基本类型|当结果为 `false` 时保存的值<br />若不填则保存 `false`|\-|`false`|\-|

|返回类型|描述|
|---|---|
|基本类型|与开关状态一致，但若 `negate` 为真，配置值为开关状态取反。<br />若存在，配置值会被 `trueValue` 或 `falseValue` 代替。|


# 主题

|主题键|类型|描述|
|---|---|---|
|offTintColor|*颜色*|关闭时开关底色|
|onTintColor|*颜色*|开启时开关底色|
|thumbTintColor|*颜色*|开关中心色|


## 示例

```lua
{
    default = true;
    label = "启用某功能";
    cell = "Switch";
    key = "enabled";  -- 该项存储的键，读取该键配置时需要用到
};
{
    default = false;
    label = "带图标的开关";
    cell = "Switch";
    key = "enabled1";  -- 该项存储的键，读取该键配置时需要用到
    icon = "res/16.png";  -- 其它有些组件也可以设置图标
    readonly = true;  -- 所有组件都支持禁用
};
```

![XUI-Switch.png](XUIScreenshots/XUI-Switch.png)

---

Source: [虚拟按键选择器](https://xxtouch.app/docs/XUI/Snippet/key.md)
Path: XUI/Snippet/key.md

# 虚拟按键选择器

「虚拟按键选择器」提供了一个虚拟按键列表，如 HOME 键、音量 + 键、音量 - 键、电源键等等，并允许用户选择其中一种虚拟按键。

「虚拟按键选择器」类型为 `key`，其返回值为 **字符串**，是用户所选虚拟按键的键码，键码列表参见 [示例及支持的键码列表](/docs/handbook/key/samples.md)。


## 示例

```lua
local group, name

group = '模拟'
name = 'key.press(key)'

return {
    name = string.format('%s - %s', group, name),
    description = "松开按下的物理按键",
    arguments = {
        {type = 'key'},
    },
    default = "HOME",  -- 默认选择的键码
    generator = function(key)
        return string.format('key.press(%q)', key)
    end,
}
```

![IMG_0008.PNG](XUIScreenshots/IMG_0008.PNG)

---

Source: [Button 动作按钮](https://xxtouch.app/docs/XUI/Modules/Button.md)
Path: XUI/Modules/Button.md

# Button 动作按钮

此组件在界面上显示一个按钮，用于执行一个动作。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|action|字符串|动作标识|*|\-|\-|
|args|字典|传递给动作的参数|*|\-|\-|
|alignment|字符串|对齐方式|\-|Left|1.2-10|

|alignment|描述|
|---|---|
|Left|左对齐|
|Center|居中|
|Right|右对齐|
|Natural|自然对齐|
|Justified|两边对齐|


# 动作说明

动作执行完成后，会将返回值保存到该组件的配置项中，因此需要正确设置该组件的 `key` 和 `defaults` 属性。

**不同的 `action` 动作需要传递不同的参数字典 `args`.**


`Reload:`

刷新 XUI，重新加载所有运行中的 XUI 实例，需要 XXT v1.2-10 及更高版本。

*无参数，无返回值*


`RunCommand:`

调用 `system`/`posix_spawn` 执行命令行，需要 XXT v1.2-10 及更高版本。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|command|字符串|欲执行的命令行字符串|*|\-|1.2-10|

|返回值类型|描述|
|---|---|
|整数|命令行执行的返回值 *Exit Status*|


`LaunchScript:`

运行服务脚本。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|path|字符串|服务脚本路径|*|\-|\-|

*无返回值*


`OpenURL:`

在第三方应用中打开 URL.

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|url|字符串|欲打开的URL|*|\-|\-|

*无返回值*


`ScanQRCode:`

调起相机，扫描二维码。

*无参数*

|返回值类型|描述|
|---|---|
|字符串|二维码扫描结果|


`SendMail:`

在应用中，发送邮件。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|subject|字符串|邮件主题|*|\-|\-|
|toRecipients|包含字符串的数组|收件邮箱地址数组|*|\-|\-|
|ccRecipients|包含字符串的数组|抄送邮箱地址数组|\-|`{}`|\-|
|bccRecipients|包含字符串的数组|密送邮箱地址数组|\-|`{}`|\-|
|attachments|包含字符串的数组|携带附件的路径数组|\-|`{}`|\-|

*无返回值*


`Null:`

无动作，一般用于重置一个特定的配置值，并发出相应通知给脚本，需要 XXT v1.2-10 及更高版本。

*无参数，无返回值*


## 示例

```lua
{
    cell = "Button";
    action = "OpenURL:";
    label = "联系 info@xxtouch.app";
    args = {
        url = "mailto:info@xxtouch.app";
    }
};
```

![XUI-Button.png](XUIScreenshots/XUI-Button.png)

---

Source: [地理位置选择器](https://xxtouch.app/docs/XUI/Snippet/loc.md)
Path: XUI/Snippet/loc.md

# 地理位置选择器

「地理位置选择器」提供了系统地图组件，允许用户使用大头钉定位一个地理位置。

「地理位置选择器」类型为 `loc`，其返回值为 **字典**，包含了所选地理位置的经纬度信息。

|键|类型|描述|
|---|---|---|
|latitude|数值|纬度|
|longitude|数值|经度|


## 示例

```lua
local group, name

group = '辅助'
name = 'loc = {latitude, longitude}'

return {
    name = string.format('%s - %s', group, name),
    description = "地理位置选择",
    arguments = {
        {type = 'loc', hint = '选择需要的位置'},
    },
    default = {
        latitude = 39.92,
        longitude = 116.46
    },  -- 默认所在的位置
    generator = function(loc)
        return string.format('loc = {%f, %f}', loc.latitude, loc.longitude)
    end,
}
```

![IMG_0007.PNG](XUIScreenshots/IMG_0007.PNG)

---

Source: [XUI 支持的 API](https://xxtouch.app/docs/XUI/Internal_Lua_Module.md)
Path: XUI/Internal_Lua_Module.md

# XUI 支持的 API

`.xui` 脚本是一种特殊的 Lua 脚本，额外支持调用少量服务模块，主要用于设备类型判断、界面重载、配置数据读写等。以下是 `.xui` 脚本中支持的 API 列表，未列出的 API 均不可在 `.xui` 脚本中使用：


## XPP 与 XUI 模块

- [XPP 脚本包模块](/docs/handbook/xpp/index.md) `xpp`
- [XUI 脚本配置界面模块](/docs/handbook/xui/index.md) `xui`


## 扩展字符串模块 (string)

- [比较两个版本号大小](/docs/handbook/ext-string/string.compare_version.md) `string.compare_version`


## 应用程序模块 (app)

- [前台打开一个 URL](/docs/handbook/app/app.open_url.md) `app.open_url`


## 屏幕模块（screen）

- [获取屏幕尺寸](/docs/handbook/screen/screen.size.md) `screen.size`


## 系统模块（sys）

- [获取系统版本](/docs/handbook/sys/sys.version.md) `sys.version`
- [获取 XXTouch 版本](/docs/handbook/sys/sys.xtversion.md) `sys.xtversion`


## 设备相关模块（device）

- [获取设备类型](/docs/handbook/device/device.type.md) `device.type`
- [获取设备名](/docs/handbook/device/device.name.md) `device.name`


## PLIST 文件读写模块 (plist)

- [读取 plist 文件](/docs/handbook/plist/plist.read.md) `plist.read`
- [写入 plist 文件](/docs/handbook/plist/plist.write.md) `plist.write`


## JSON 模块 (json)

- [将 Lua 值转成 JSON 字符串](/docs/handbook/json/json.encode.md) `json.encode`
- [将 JSON 字符串转换成 Lua 值](/docs/handbook/json/json.decode.md) `json.decode`
- [JSON 中的 NULL 常量](/docs/handbook/json/json.null.md) `json.null`

---

Source: [TextField 单行文本框](https://xxtouch.app/docs/XUI/Modules/TextField.md)
Path: XUI/Modules/TextField.md

# TextField 单行文本框

此组件在界面上显示一个文本框，用于字符串输入。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|alignment|字符串|对齐方式|\-|`Left`|\-|
|keyboard|字符串|键盘类型|\-|`Default`|\-|
|placeholder|字符串|文本框占位符|可本地化|`""`|\-|
|isSecure|布尔型|字符是否显示为小圆点|\-|`false`|\-|
|clearButtonMode|字符串|是否显示清除小黑叉|\-|`Never`|\-|
|maxLength|整数|最大文本长度|\-|`INT_MAX`|\-|
|validationRegex|字符串|用于验证字符串条目的正则表达式|\-|`nil`|1.2-10|
|prompt|字符串|提示框标题|可本地化|`nil`|1.2-10|
|message|字符串|提示框信息|可本地化|`nil`|1.2-10|
|okTitle|字符串|提示框确定按钮标题|可本地化|`"好"`|1.2-10|
|cancelTitle|字符串|提示框取消按钮标题|可本地化|`"取消"`|1.2-10|

此组件不支持 `icon`。若设置 `title` 属性，建议将 `alignment` 属性设为 "Right".

修改或添加字符串条目时，若字符串无法通过[正则表达式](https://tool.oschina.net/regex/) `validationRegex` 验证，则无法保存当前条目。

`prompt` 或 `message` 不为空时，轻按 `TextField`，会弹出提示框，并要求在提示框中输入值。

|alignment|描述|
|---|---|
|Left|左对齐|
|Center|居中|
|Right|右对齐|
|Natural|自然对齐|
|Justified|两边对齐|

|keyboard|描述|
|---|---|
|Default|标准及第三方键盘|
|Alphabet|标准 ASCII|
|ASCIICapable|标准 ASCII|
|NumbersAndPunctuation|数字与标点|
|URL|网址|
|NumberPad|数字|
|PhonePad|电话号码|
|NamePhonePad|姓名与电话号码|
|EmailAddress|电子邮箱|
|DecimalPad|带小数点的数字|

|clearButtonMode|描述|
|---|---|
|Never|从不显示|
|Always|一直显示|
|WhileEditing|仅编辑时显示|
|UnlessEditing|仅不编辑时显示|

|返回类型|描述|
|---|---|
|字符串|文本框内容|


# 主题

|主题键|类型|描述|
|---|---|---|
|textColor|*颜色*|文字颜色|
|caretColor|*颜色*|光标颜色|
|placeholderColor|*颜色*|占位符颜色|


## 示例

```lua
{
    default = "";
    label = "用户名";
    cell = "TextField";
    key = "username";
    keyboard = "Default";  -- 默认键盘
    alignment = "Right";  -- 右对齐
    placeholder = "输入用户名";  -- 占位符
    maxLength = 21;  -- 最大长度
    validationRegex = "^[0-9a-zA-Z]+$";  -- 正则验证
};
{
    isSecure = true;  -- 显示为小圆点密码输入
    default = "";
    label = "密码";
    cell = "TextField";
    key = "password";
    keyboard = "NumberPad";  -- 数字小键盘
    alignment = "Right";  -- 右对齐
    placeholder = "输入密码";  -- 占位符
    prompt = "请输入密码";  -- 弹框标题
    message = "请在提示框中输入 6 位数字密码";  -- 弹框信息
    validationRegex = "^[0-9]{6}$";  -- 正则验证
    okTitle = "保存";  -- 提交按钮标题
    cancelTitle = "取消";  -- 取消按钮标题
};
```

![XUI-TextField.png](XUIScreenshots/XUI-TextField.png)

![XUI-TextField-Prompt.png](XUIScreenshots/XUI-TextField-Prompt.png)

---

Source: [图像位置与颜色选择器](https://xxtouch.app/docs/XUI/Snippet/poscolor.md)
Path: XUI/Snippet/poscolor.md

# 图像位置与颜色选择器

「图像位置与颜色选择器」提供了从系统相机胶卷与主目录选择截图，并在截图上标注一个或多个像素点，以获取其位置或颜色的能力。

类型为 `pos` 的「单个图像位置选择器」允许用户选择一个像素点，并获取它的位置，其返回值为 **包含两个数值的数组**，两个数值分别为像素点的 x 坐标和 y 坐标，如：

```lua
{ 512, 373 }
```

类型为 `color` 的「单个图像颜色选择器」允许用户选择一个像素点，并获取它的颜色，其返回值为像素点颜色 **RGB 的数值形式**，如：

```lua
0x3c1f8b
```

类型为 `poscolor` 的「单个图像位置与颜色选择器」允许用户选择一个像素点，并获取它的位置与颜色，其返回值为 **包含三个数值的数组**，三个数值分别为像素点的 x 坐标、像素点的 y 坐标、像素点颜色 RGB 的数值形式，如：

```lua
{ 512, 373, 0x3c1f8b }
```

类型为 `poscolors` 的「多个图像位置与颜色选择器」允许用户选择一个或多个像素点，并获取它们的位置与颜色，其返回值为 **二维数组**，包含了所有所选各像素点的 x 坐标、像素点的 y 坐标、像素点颜色 RGB 的数值形式，如：

```lua
{
    { 512, 373, 0x3c1f8b },
    { 512, 374, 0x3c1f7c },
    { 512, 375, 0x3c1f89 },
    -- ...
}
```


## 示例

```lua
local group, name

group = '图色'
name = 'if (screen.is_colors(poscolors, 90)) then ... end'

return {
    name = string.format('%s - %s', group, name),
    description = "屏幕多点颜色匹配",
    arguments = {
        {type = 'poscolors'},
    },
    -- default = nil,  -- 该选择器暂不支持默认值
    generator = function(poscolors)
        local pcs = {}
        for i, pc in ipairs(poscolors) do
            pcs[#pcs + 1] = string.format('\t{ %4d, %4d, 0x%06x}, -- %3d\n', pc[1], pc[2], pc[3] & 0x00ffffff, i)
        end
        return string.format([[
if (screen.is_colors({
%s}, 90)) then
    @@
end]], table.concat(pcs))  -- 在返回的文本代码段中插入 @@，可以使编辑器光标自动移动到此处。
    end,
}
```

![IMG_0009.PNG](XUIScreenshots/IMG_0009.PNG)

![IMG_0010.PNG](XUIScreenshots/IMG_0010.PNG)

![IMG_0013.PNG](XUIScreenshots/IMG_0013.PNG)

---

Source: [Radio / Checkbox 单选框 / 复选框组](https://xxtouch.app/docs/XUI/Modules/Radio_Checkbox.md)
Path: XUI/Modules/Radio_Checkbox.md

# Radio / Checkbox 单选框 / 复选框组

此组件在界面上显示若干单选框 / 复选框。

点选**单选框**会选中当前选择的单选框，取消同组其它单选框的选中状态。
点选**复选框**会切换其选中 / 未选状态。

|键|类型|描述|必选|默认值|最低版本需求|备注|
|---|---|---|---|---|---|---|
|options|包含字典的数组|选项列表数组|*|\-|\-|\-|
|numPerLine|整数|每行选项个数|\-|iPhone 为 `2`, iPad 为 `4`|1.2-10|最大值为 `12`|
|minCount|整数|最少选择项目数|\-|`0`|\-|`cell = 'Checkbox'`|
|maxCount|整数|最多选择项目数|\-|`INT_MAX`|\-|`cell = 'Checkbox'`|

`options` 包含若干 *选项*, *选项* 为字典，有如下属性:

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|选项标题|可本地化|
|value|基本类型|选项配置值<br />若不填，则与 `title` 一致。|可选|

此组件不支持 `label`/`icon`/`height`，如需要设置标题或备注，请结合 `Group` 组件进行设计。

|返回类型|描述|
|---|---|
|包含基本类型的数组|包含所有选中项 `value` 的数组|


# 主题

|主题键|类型|描述|
|---|---|---|
|tagTextColor|*颜色*|标签文字颜色|
|tagSelectedTextColor|*颜色*|选中标签文字颜色|
|tagBackgroundColor|*颜色*|标签背景颜色|
|tagSelectedBackgroundColor|*颜色*|选中标签背景颜色|
|tagBorderColor|*颜色*|标签边框颜色|
|tagSelectedBorderColor|*颜色*|选中标签边框颜色|


## 示例

```lua
{
    cell = "Group";
    label = "多选框组";
    footerText = "轻按以选中标签，再次轻按以取消选中，最多选择 4 项";
};
{
    default = {
        "红色";
        "绿色";
    };
    cell = "Checkbox";
    key = "checkbox";
    maxCount = 4;
    numPerLine = 4;  -- 每行选项数量
    options = {
        {
            title = "红色";
        };
        {
            title = "绿色";
        };
        {
            title = "蓝色";
        };
        {
            title = "黄色";
        };
        "紫色";
        "黑色";
        "白色";
        "咖啡色";
        "卡其色";
        "灰色";
    };
};
{
    cell = "Group";
    label = "单选框组";
    footerText = "轻按以选中标签";
};
{
    default = "Fifth";
    cell = "Radio";
    key = "radio";
    options = {
    {
        title = "第一";
    };
    {
        title = "第二";
    };
    {
        title = "第三";
    };
    {
        title = "第四";  -- 如果选项未设置 value，则该选项配置值为 title
    };
    {
        title = "第五";
        value = "Fifth";  -- 如果选项设置了 value，则该选项配置值为 value
    };
    "倒数第一";  -- 选项可以简写
    };
};
```

![XUI-Radio.png](XUIScreenshots/XUI-Radio.png)

![XUI-Checkbox.png](XUIScreenshots/XUI-Checkbox.png)

---

Source: [图像区域选择器](https://xxtouch.app/docs/XUI/Snippet/rect.md)
Path: XUI/Snippet/rect.md

# 图像区域选择器

「图像区域选择器」提供了从系统相机胶卷与主目录选择截图，并在截图上标注一个矩形区域，以获取其顶点与尺寸的能力。

「图像区域选择器」类型为 `rect`，其返回值为 **包含四个数值的数组**，这四个数值分别为矩形区域左上角顶点的 x 坐标和 y 坐标、右下角顶点的 x 坐标和 y 坐标，如：

```lua
{ 0, 534, 295, 626 }
```


## 示例

```lua
local group, name

group = '图色'
name = 'text = screen.ocr_text(rect)'

return {
    name = string.format('%s - %s', group, name),
    description = "屏幕区域文字识别",
    arguments = {
        {type = 'rect'},
    },
    generator = function(rect)
        return string.format('text = screen.ocr_text(%d, %d, %d, %d)', rect[1], rect[2], rect[3], rect[4])
    end,
}
```

![IMG_0015.PNG](XUIScreenshots/IMG_0015.PNG)

---

Source: [Segment 适合少量选项的单项选择](https://xxtouch.app/docs/XUI/Modules/Segment.md)
Path: XUI/Modules/Segment.md

# Segment 适合少量选项的单项选择

此组件在界面上显示一个选项组。用于选择单个选项 (总选项数一般少于 6 个).

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|options|包含字典的数组|选项列表数组|*|\-|\-|

`options` 包含若干 *选项*, *选项* 为字典，有如下属性:

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|选项标题|可本地化|
|value|基本类型|选项配置值<br />若不填，则与 `title` 一致。|可选|

此组件不支持 `icon`。

|返回类型|描述|
|---|---|
|基本类型|选中项的 `value`|


## 示例

```lua
{
    default = "蓝色";
    label = "分块选项列表";
    cell = "Segment";
    key = "list-segment";
    options = {
        {
            title = "红色";
        };
        {
            title = "蓝色";
        };
        {
            title = "灰色";
        };
        {
            title = "黄色";
        };
    };
};
```

![XUI-Segment.png](XUIScreenshots/XUI-Segment.png)

---

Source: [Option 单项选择列表](https://xxtouch.app/docs/XUI/Modules/Option.md)
Path: XUI/Modules/Option.md

# Option 单项选择列表

此组件在界面上显示一个子菜单项，用于链接包含一些选项的子菜单。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|options|包含字典的数组|选项列表数组|*|\-|\-|
|footerText|字符串|显示在列表选项下方的小字|可本地化|`""`|\-|
|popoverMode|布尔型|采用悬浮样式|\-|`false`|1.2-4|

`options` 包含若干 *选项*, *选项* 为字典，有如下属性:

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|选项标题|可本地化|
|value|基本类型|选项配置值<br />若不填，则与 `title` 一致。|可选|
|icon|字符串|选项图标文件名|可选|
|shortTitle|字符串|显示在父级菜单右侧的标题|可选，可本地化|

|返回类型|描述|
|---|---|
|基本类型|选中项的 `value`|


## 示例

```lua
{
    default = "绿色";  -- 默认值
    label = "单选列表";
    cell = "Option";
    key = "list-1";
    options = {
        {
            title = "红色";
            shortTitle = "红色";  -- 显示在父级入口右侧
        };
        {
            title = "绿色";
            shortTitle = "绿色";
        };
        {
            title = "蓝色";
            shortTitle = "蓝色";
        };
    };
    popoverMode = false;  -- 设为 true 可使用悬浮模式
    -- footerText = "只能选择一项"; -- 底部提示信息
};
```

![XUI-Option-1.png](XUIScreenshots/XUI-Option-1.png)

![XUI-Option-2.png](XUIScreenshots/XUI-Option-2.png)

---

Source: [MultipleOption 多项选择列表](https://xxtouch.app/docs/XUI/Modules/MultipleOption.md)
Path: XUI/Modules/MultipleOption.md

# MultipleOption 多项选择列表

此组件在界面上显示一个子菜单项，用于链接包含一些选项的子菜单。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|options|包含字典的数组|选项列表数组|*|\-|\-|
|footerText|字符串|显示在列表选项下方的小字|可本地化|`""`|\-|
|maxCount|整数|最多选择项目数|\-|`INT_MAX`|\-|
|popoverMode|布尔型|采用悬浮样式|\-|`false`|1.2-4|

`options` 包含若干 *选项*, *选项* 为字典，有如下属性:

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|选项标题|可本地化|
|value|基本类型|选项配置值<br />若不填，则与 `title` 一致。|可选|
|icon|字符串|选项图标文件名|可选|

|返回类型|描述|
|---|---|
|包含基本类型的数组|包含所有选中项 `value` 的数组|


## 示例

```lua
{
    default = {
        "红色";
        "绿色";
    };
    label = "多选列表";
    cell = "MultipleOption";
    key = "list-2";
    maxCount = 2;  -- 最大选项数量
    options = {
        {
            title = "红色";
            icon = "res/red.png";  -- 为选项设置图标
        };
        {
            title = "绿色";
            icon = "res/green.png";
        };
        {
            title = "蓝色";
            icon = "res/blue.png";
        };
    };
    popoverMode = false;  -- 设为 true 可使用悬浮模式
    footerText = "最多可以选择两项";  -- 底部提示信息
};
```

![XUI-MultipleOption-1.png](XUIScreenshots/XUI-MultipleOption-1.png)

![XUI-MultipleOption-2.png](XUIScreenshots/XUI-MultipleOption-2.png)

---

Source: [OrderedOption 多项有序选择列表](https://xxtouch.app/docs/XUI/Modules/OrderedOption.md)
Path: XUI/Modules/OrderedOption.md

# OrderedOption 多项有序选择列表

此组件在界面上显示一个子菜单项，用于链接包含一些选项的子菜单。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|options|包含字典的数组|选项列表数组|*|\-|\-|
|footerText|字符串|显示在列表选项下方的小字|可本地化|`""`|\-|
|popoverMode|布尔型|采用悬浮样式|\-|`false`|1.2-4|
|minCount|整数|最少选择项目数|\-|`0`|\-|
|maxCount|整数|最多选择项目数|\-|`INT_MAX`|\-|

`options` 包含若干 *选项*, *选项* 为字典，有如下属性:

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|选项标题|可本地化|
|value|基本类型|选项配置值<br />若不填，则与 `title` 一致。|可选|
|icon|字符串|选项图标文件名|可选|

|返回类型|描述|
|---|---|
|包含基本类型的数组|包含所有选中项 `value` 的数组|


## 示例

```lua
{
    default = {
        "红色";
    };
    label = "有序选项列表";
    cell = "OrderedOption";
    key = "list-3";
    maxCount = 2;  -- 最大选项数量
    minCount = 1;  -- 最小选项数量
    options = {
        {
            title = "红色";
            -- value = "Red";  -- 如果设置了 value，则配置项会保存 value
            icon = "res/red.png";
        };
        {
            title = "绿色";
            -- value = "Green";
            icon = "res/green.png";
        };
        {
            title = "蓝色";
            -- value = "Blue";
            icon = "res/blue.png";
        };
    };
    popoverMode = false;  -- 设为 true 可使用悬浮模式
    footerText = "最多选择两项，最少选择一项";  -- 底部提示信息
};
```

![XUI-OrderedOption-1.png](XUIScreenshots/XUI-OrderedOption-1.png)

![XUI-OrderedOption-2.png](XUIScreenshots/XUI-OrderedOption-2.png)

![XUI-OrderedOption-Popover.png](XUIScreenshots/XUI-OrderedOption-Popover.png)

---

Source: [EditableList 可编辑列表](https://xxtouch.app/docs/XUI/Modules/EditableList.md)
Path: XUI/Modules/EditableList.md

# EditableList 可编辑列表

此组件在界面上显示一个子菜单项，用于链接一个可编辑的字符串列表。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|footerText|字符串|显示在列表选项下方的小字|可本地化|`""`|\-|
|itemFooterText|字符串|显示在添加新项目页面下方的小字|可本地化|`""`|\-|
|maxCount|整数|最多选择项目数|\-|`INT_MAX`|\-|
|validationRegex|字符串|用于验证字符串条目的正则表达式|\-|`nil`|1.2-10|

修改或添加字符串条目时，若字符串无法通过正则表达式 `validationRegex` 验证，则无法保存当前条目。

|返回类型|描述|
|---|---|
|包含字符串的数组|列表内容|


# 主题

|主题键|类型|描述|
|---|---|---|
|textColor|*颜色*|文字颜色|
|caretColor|*颜色*|光标颜色|
|placeholderColor|*颜色*|占位符颜色|


## 示例

```lua
{
    maxCount = 10;
    cell = "EditableList";
    label = "可编辑列表";
    key = "list-4";
    default = {
        "Default";
    };
    validationRegex = "^[0-9a-zA-Z]+$";
};
```

![XUI-EditableList-1.png](XUIScreenshots/XUI-EditableList-1.png)

![XUI-EditableList-2.png](XUIScreenshots/XUI-EditableList-2.png)

---

Source: [Slider 数值拖拽滑块](https://xxtouch.app/docs/XUI/Modules/Slider.md)
Path: XUI/Modules/Slider.md

# Slider 数值拖拽滑块

此组件在界面上显示一个滑块，用于浮点数值的选择和调整。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|min|数值|滑块最小值|\-|`0.0`|\-|
|max|数值|滑块最大值|\-|`1.0`|\-|
|step|数值|调节步长，滑块会自动紧贴最近的步长值|\-|`0`|1.2-10|
|showValue|布尔型|是否显示当前滑块的值|\-|`false`|\-|

此组件不支持 `label`/`icon`，如需要设置标题或备注，请结合 `Group` 组件进行设计。

|返回类型|描述|
|---|---|
|数值|组件数值|


# 主题

|主题键|类型|描述|
|---|---|---|
|tintColor|*颜色*|滑块进度底色|
|thumbColor|*颜色*|滑块中心色|


## 示例

```lua
{
    showValue = true;  -- 是否显示当前值
    min = 1;  -- 最小值
    default = 5;  -- 默认值
    max = 10;  -- 最大值
    step = 0.5;  -- 可以设置步进间隔
    label = "滑动控件";
    cell = "Slider";
    key = "slider";
};
```

![XUI-Slider.png](XUIScreenshots/XUI-Slider.png)

---

Source: [Stepper 数值调节按钮](https://xxtouch.app/docs/XUI/Modules/Stepper.md)
Path: XUI/Modules/Stepper.md

# Stepper 数值调节按钮

此组件在界面上显示一个调节器，用于数值的选择和调整。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|min|数值|调节最小值|\-|`1`|\-|
|max|数值|调节最大值|\-|`100`|\-|
|step|数值|调节步长|\-|`1`|\-|
|isInteger|布尔型|值是否显示为整数|\-|`false`|\-|
|autoRepeat|布尔型|长按是否连续调整|\-|`true`|\-|

此组件不支持 `icon`。

|返回类型|描述|
|---|---|
|数值|组件数值|


## 示例

```lua
{
    min = 1;
    default = 25;
    max = 100;
    autoRepeat = true;  -- 长按自动重复触发
    label = "步进控件";
    cell = "Stepper";
    key = "stepper";
    isInteger = true;  -- 是否显示为整数
};
```

![XUI-Stepper.png](XUIScreenshots/XUI-Stepper.png)

---

Source: [DateTime 时间日期选择器](https://xxtouch.app/docs/XUI/Modules/DateTime.md)
Path: XUI/Modules/DateTime.md

# DateTime 时间日期选择器

此组件在界面上显示一个时间日期选择器，用于日期、时间的选择及时间间隔的调整。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|min|数值|时间间隔最小值|\-|`0`|\-|
|max|数值|时间间隔最大值|\-|`FLOAT_MAX`|\-|
|minuteInterval|整数|时间间隔步长，单位分钟|\-|`1`|\-|
|mode|字符串|选择器模式|\-|`datetime`|\-|
|format|字符串|时间格式 (ISO8601)|\-|`nil`|\-|

此组件不支持 `label`/`icon`，如需要设置标题和描述，请配合 `Group` 组件进行设计。

|mode|描述|
|---|---|
|datetime|日期时间选择器|
|date|日期选择器|
|time|时间选择器|
|interval|时间间隔选择器|

|返回类型|条件|描述|
|---|---|---|
|整数|`format == nil`|组件所选时间的 Unix 时间戳，或时间间隔的秒数|
|字符串|`#format > 0`|组件所选时间按 `format` 进行格式化后的结果|

`format` 时间日期格式请参见 [Unicode: Date Format Patterns](https://www.unicode.org/reports/tr35/tr35-31/tr35-dates.html#Date_Format_Patterns)


## 示例

```lua
{
    cell = "DateTime";
    key = "datetime1";
};
```

![XUI-DateTime.png](XUIScreenshots/XUI-DateTime.png)

---

Source: [TitleValue 键值对显示; 代码片段选择器](https://xxtouch.app/docs/XUI/Modules/TitleValue.md)
Path: XUI/Modules/TitleValue.md

# TitleValue 键值对显示; 代码片段选择器

此组件在界面上显示 `key` / `value` 键值对，类似"设置 → 通用 → 关于本机"中系统参数的显示方式。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|value|基本类型|右侧显示值|\-|`nil`|\-|
|snippet|字符串|选择器脚本文件名|\-|`nil`|\-|

此组件可以左划将已存的配置值置空，但不能覆盖 XUI 中提供的 `value`。

如果为此组件设置了配置分区文件名 `defaults` 和配置键名 `key`，则可用来显示某一 XUI 配置项的实际值。若同时设置了 `.snippet` 代码片段模板文件名，则可为此组件启用 **代码片段选择器** 功能——点击该组件即可唤起选择器队列，队列处理完成后将返回结果存入此组件的配置项中。具体使用方法参见 [代码片段](/docs/XUI/Snippet/index.md)。


## 示例

```lua
{
    cell = "Group";
    label = "二维码";
    footerText = "扫描结果会出现在扫码内容中";
};
{
    cell = "Button";
    label = "打开二维码扫描器";
    key = "qr1";
    action = "ScanQRCode:";
    args = {};
};
{
    cell = "TitleValue";
    label = "扫码内容";
    key = "qr1";
};
```

![XUI-TitleValue-QR.png](XUIScreenshots/XUI-TitleValue-QR.png)

![XUI-TitleValue-Snippets.png](XUIScreenshots/XUI-TitleValue-Snippets.png)

---

Source: [StaticText 静态文本框](https://xxtouch.app/docs/XUI/Modules/StaticText.md)
Path: XUI/Modules/StaticText.md

# StaticText 静态文本框

此组件在界面上显示一段静态文本，即其 `label` 属性中的文本。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|label|字符串|显示的文本|*|\-|\-|
|alignment|字符串|对齐方式|\-|`Left`|\-|
|selectable|布尔型|是否允许选择文本|\-|`false`|\-|

|alignment|描述|
|---|---|
|Left|左对齐|
|Center|居中|
|Right|右对齐|
|Natural|自然对齐|
|Justified|两边对齐|

此组件不支持 `icon`/`height`，且暂不支持更改文本字体、尺寸等属性。


## 示例

```lua
{
    cell = "Group";
    label = "静态文本";
};
{
    cell = "StaticText";
    label = "这里是一条静态文本";
};
{
    cell = "StaticText";
    label = "这里是一条可以被选中文字的静态文本";
    selectable = true;  -- 允许选中
};
```

![XUI-StaticText.png](XUIScreenshots/XUI-StaticText.png)

---

Source: [Textarea 多行文本域](https://xxtouch.app/docs/XUI/Modules/Textarea.md)
Path: XUI/Modules/Textarea.md

# Textarea 多行文本域

此组件在界面上显示一个子菜单项，用于链接到一个多行文本输入界面。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|maxLength|整数|最大文本长度|\-|`INT_MAX`|\-|
|keyboard|字符串|键盘类型|\-|`Default`|\-|
|autoCapitalization|字符串|自动大写模式|\-|`None`|\-|
|autoCorrection|字符串|自动更正模式|\-|`Default`|\-|

|keyboard|描述|
|---|---|
|Default|标准及第三方键盘|
|Alphabet|标准 ASCII|
|ASCIICapable|标准 ASCII|
|NumbersAndPunctuation|数字与标点|
|URL|网址|
|NumberPad|数字|
|PhonePad|电话号码|
|NamePhonePad|姓名与电话号码|
|EmailAddress|电子邮箱|
|DecimalPad|带小数点的数字|

|autoCapitalization|描述|
|---|---|
|None|无|
|Sentences|按句自动大写|
|Words|按单词自动大写|
|AllCharacters|全部大写|

|autoCorrection|描述|
|---|---|
|Default|默认|
|No|关闭自动更正|
|Yes|打开自动更正|

*暂不支持更改文本字体、尺寸等属性*

|返回类型|描述|
|---|---|
|字符串|文本内容|


# 主题

|主题键|类型|描述|
|---|---|---|
|textColor|*颜色*|文字颜色|
|caretColor|*颜色*|光标颜色|
|placeholderColor|*颜色*|占位符颜色|


## 示例

```lua
{
    default = "You can enter any text here...";
    cell = "Textarea";
    key = "textarea";
    label = "一个文本域";
};
```

![XUI-Textarea-1.png](XUIScreenshots/XUI-Textarea-1.png)

![XUI-Textarea-2.png](XUIScreenshots/XUI-Textarea-2.png)

---

Source: [Image / AnimatedImage 图片 / 动态图片](https://xxtouch.app/docs/XUI/Modules/Image_AnimatedImage.md)
Path: XUI/Modules/Image_AnimatedImage.md

# Image / AnimatedImage 图片 / 动态图片

此组件在界面上显示图片。

`Image` 组件仅支持本地静态图片，如 `.png` 和 `.jpg` 等。`AnimatedImage` 组件支持 `.gif` 动态图。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|path|字符串|本地图片名称，或在线图片的 URL|*|\-|\-|

此组件必须设定通用属性 `height`，以确定图片高度，宽度将保持比例自动适应。

`AnimatedImage` 在 XXTouch v1.2-11 及更高版本中，还支持加载在线静态或动态图片，并在加载完成后进行缓存。在 `path` 中填写在线图片的 URL 即可（仅支持 http/https 协议）。


## 示例

```lua
{
    cell = "Image";
    path = "res/bd_logo1_31bdc765.png";
    height = 128.0;
};
{
    cell = "AnimatedImage";
    path = "https://www.baidu.com/img/540%20258_c622d80176946df7f7b8d1997edf57d4.gif";
    height = 128.0;
};
```

![XUI-Image.png](XUIScreenshots/XUI-Image.png)

---

Source: [File 文件选择器](https://xxtouch.app/docs/XUI/Modules/File.md)
Path: XUI/Modules/File.md

# File 文件选择器

此组件在界面上显示文件选择区域，可显示文件类型图标、文件名称与文件修改时间，点击可选择新文件。通常用于选择数据文件，提供路径给服务脚本使用。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|initialPath|字符串|文件选择初始顶层目录|\-|XPP 根路径|\-|
|allowedExtensions|包含字符串的数组|允许的文件扩展名列表|\-|`[]`|\-|
|label|字符串|未选择文件时的提示标题|可本地化|`""`|1.2-10|
|footerText|字符串|未选择文件时的提示信息|可本地化|`""`|1.2-10|
|isFile|布尔型|是否选择文件，如果为 `false` 则选择目录|\-|`true`|1.2-10|

此组件可以左划会显示删除按钮，轻按删除按钮可将已存的配置值置空。

`initialPath` 是相对于 XPP 脚本包的相对路径。若不填，则为当前脚本包路径。

`allowedExtensions` 中包含允许选择的文件名列表，不符合扩展名要求的项目将不会被显示，更无法被选择。

|返回类型|描述|
|---|---|
|字符串|所选文件完整绝对路径|


# 主题

|主题键|类型|描述|
|---|---|---|
|labelColor|*颜色*|文件名颜色|
|valueColor|*颜色*|文件描述颜色|


## 示例

```lua
{
    cell = "File";
    key = "file1";
    initialPath = "scripts";
    isFile = true;  -- 选择文件
    label = "请选择一个脚本";  -- 标题
    -- footerText = "可选择所有 XXT 支持的脚本格式";  -- 描述
    allowedExtensions = { "lua"; "xxt"; "xpp" };  -- 只允许选择这些扩展名的文件
};
```

![XUI-File.png](XUIScreenshots/XUI-File.png)

---

Source: [About 关于](https://xxtouch.app/docs/XUI/Modules/About.md)
Path: XUI/Modules/About.md

# About 关于

此组件在界面上显示一个关于区域。

|键|类型|描述|必选|默认值|最低版本需求|
|---|---|---|---|---|---|
|icon|字符串|关于图标的相对路径|\-|`""`|\-|

此组件需要设定通用属性 `label`/`value`，分别显示为标题/副标题。


# 主题

|主题键|类型|描述|
|---|---|---|
|tintColor|*颜色*|标题颜色|
|labelColor|*颜色*|副标题颜色|


## 示例

```lua
{
    cell = "About";
    imagePath = "res/xxt-icon.png";  -- 中间图标
    label = "XUI 示例\nv1.2-10";  -- 标题
    value = "适用于 XXTouch v1.2-10 及以上版本, 示例内容仅供参考, 请勿直接用于生产环境.\n2016-2018 (c) XXTouch Team.\nAll Rights Reserved.";  -- 副标题
};
```

![XUI-About.png](XUIScreenshots/XUI-About.png)

---

Source: [通用属性](https://xxtouch.app/docs/XUI/Creation/General.md)
Path: XUI/Creation/General.md

# 通用属性

各组件均可使用如下通用属性，用于添加标题、图标、指定配置保存位置等。这些通用属性在不同组件中可能有不同的作用。

|键|类型|描述|条件|
|---|---|---|---|
|cell|字符串|组件类型|\-|
|label|字符串|显示标签|可选，可本地化|
|defaults|字符串|配置分区标识符，即该组件配置存储的名称|\-|
|key|字符串|配置键名|`defaults != nil`|
|default|字符串|配置默认值|\-|
|value|基本类型|配置值|可选|
|icon|字符串|图标文件名|可选|
|readonly|布尔型|组件是否只读|可选|
|height|数值|组件的高度|可选|

`cell` 为组件类型，不同类型代表不同的 XUI 组件，如 `Button`，`Switch`, `Link` 等。

`label` 为组件标题，通常显示在组件左侧。

`default` 为组件默认值，若 `value` 为 `nil`，则使用 `default` 的值填充 `value`。

`icon` 为图标，显示在 `label` 左侧。若设置为 `res/16.png`，建议同时准备 `res/16@2x.png` 和 `res/16@3x.png`，实际尺寸须分别为原来的 2 倍和 3 倍。

`readonly` 如果为 `true`，则组件的值只读，不能被修改和置空。也不能链接到子界面。

---

Source: [读取配置](https://xxtouch.app/docs/XUI/Creation/ReadSettings.md)
Path: XUI/Creation/ReadSettings.md

# 读取配置

配置完成后，在 `defaults` 指定的保存位置，读取 plist 中键 `key` == "switch-1" 的值，即为开关 "switch-1" 的状态。读取、写入及更新 XUI 配置，可参见 [XUI 脚本配置界面模块](/docs/handbook/xui/index.md).

```lua
local switch1 = xui.get("com.yourcompany.A-Script-Bundle", "switch-1")
if (switch1) then
    -- ...
end
```

---

Source: [根](https://xxtouch.app/docs/XUI/Creation/Root.md)
Path: XUI/Creation/Root.md

# 根

XUI 配置的根（顶层）为字典。

|键|类型|描述|条件|
|---|---|---|---|
|title|字符串|导航栏标题|可选，可本地化|
|header|字符串|主标题|可选，可本地化|
|subheader|字符串|副标题|可选，可本地化|
|defaults|字符串|配置分区标识符，即全局配置文件存储的名称|\-|
|items|包含字典的数组|组件列表|\-|
|theme|字典|界面主题样式|可选|
|stringsTable|字符串|多语言表名称，默认为 `Localizable`|可选|

`defaults` 为配置分区标识符，指定了各组件配置项存储的位置，例如设置 `defaults` 为 `com.yourcompany.A-Script-Bundle`，则该 XUI 配置文件将保存到 `uicfg/com.yourcompany.A-Script-Bundle.plist` 当中。同时，也可为各组件分别设置 `defaults` 字段。

`items` 是组件列表数组，所有的 *组件字典* 按顺序存放在该数组中，即可在界面上显示。关于 *组件字典* 的说明，参见[通用属性](/docs/XUI/Creation/General.md).

`stringsTable` 仅在需要为 XUI 启用多语言支持时使用。标记为"可本地化"的属性将按照 iOS 国际化机制，从多语言表中解析并显示对应语言的内容。


```lua
return {
    title = "一个脚本包";
    header = "脚本配置演示";
    subheader = "由 XXTouch 提供的优雅的脚本配置界面";
    defaults = "com.yourcompany.A-Script-Bundle";  -- 配置存储的位置，读取配置的时候需要用到
    theme = {
        style = "Grouped";  -- 组显示风格，如果为 Plain 则为平铺显示风格
    };
    items = {
        {

        };  -- 组件 1
        {

        };  -- 组件 2
        {

        };  -- 组件 3
    };  -- 该表中存放各个组件的字典
};
```

---

Source: [主题](https://xxtouch.app/docs/XUI/Creation/Theme.md)
Path: XUI/Creation/Theme.md

# 主题

在根层级设置 `theme` 字典，可为界面配置统一的样式。所有组件及子页面都将继承根层级主题字典的所有字段。

:::tip
如需为组件单独设置样式，可在各组件字典中设置 `theme` 字典。组件的 `theme` 字段将覆盖根层级的 `theme`，产生主题合并。不同组件可拥有自身特有的主题属性，详见每个组件的 *主题键* 表格。

若组件链接到非 XUI 子页面（如 `Option`/`MultipleOption`/`OrderedOption`/`EditableList`），子页面将使用组件的 `theme` 字典；若组件链接到另一个 XUI 子页面（如 `Link`），子页面可单独设置 `theme` 字典，并与父页面的主题合并。
:::

![XUI-Dark.png](Theme/XUI-Dark.png)


# 界面

|键|类型|描述|
|---|---|---|
|style|风格|界面风格|
|tintColor|*颜色*|前景颜色|
|backgroundColor|*颜色*|背景颜色|
|separatorColor|*颜色*|组件分隔线颜色|
|backgroundImage|字符串|背景图片相对路径|


# 导航栏

|键|类型|描述|
|---|---|---|
|navigationBarColor|*颜色*|导航栏背景颜色|
|navigationTitleColor|*颜色*|导航栏标题颜色|


# 页首与页尾

|键|类型|描述|
|---|---|---|
|headerTextColor|*颜色*|`header` 文字颜色|
|subheaderTextColor|*颜色*|`subheader` 文字颜色|
|footerTextColor|*颜色*|页尾文字颜色|
|headerBackgroundColor|*颜色*|`header` 背景颜色|
|footerBackgroundColor|*颜色*|页尾背景颜色|


# 通用组件

|键|类型|描述|
|---|---|---|
|cellBackgroundColor|*颜色*|组件背景颜色|
|disclosureIndicatorColor|*颜色*|组件指示器颜色|
|selectedColor|*颜色*|选中颜色|
|highlightedColor|*颜色*|高亮颜色|
|labelColor|*颜色*|标题文字颜色|
|valueColor|*颜色*|值文字颜色|


# 状态

|键|类型|描述|
|---|---|---|
|dangerColor|*颜色*|错误颜色|
|warningColor|*颜色*|警告颜色|
|successColor|*颜色*|成功颜色|


# 风格

|style|描述|
|---|---|
|Grouped|组风格 (默认)|
|Plain|平铺风格|


类型 *颜色*，即以 `#` 开头的，十六进制 RGB/RGBA 字符串形式，如 `#FF0000` 代表红色。

---

Source: [URL Scheme 与二维码协议](https://xxtouch.app/docs/URLScheme/index.md)
Path: URLScheme/README.md

# URL Scheme 与二维码协议

该协议定义了 XXTouch App 的 URL Scheme 所支持的动作及参数。

以下三种方式均可唤醒 XXTouch App 并触发相应行为：

- 打开 `xxt://` 形式的 URL
- 扫描包含 `xxt://` 形式 URL 的二维码
- 扫描包含动作及参数字典的二维码

---

- [打开扫一扫](Scan.md)
- [运行脚本](Launch.md)
- [停止脚本](Stop.md)
- [绑定授权](License.md)
- [XUI 相关](XUI.md)
- [下载相关](Download.md)
- [恢复工作区](Workspace.md)

---

Source: [打开扫一扫](https://xxtouch.app/docs/URLScheme/Scan.md)
Path: URLScheme/Scan.md

# 打开扫一扫

```
xxt://scan/
```

唤醒扫一扫功能。

- 二维码字典

```json
{
    "event":"scan"
}
```

---

Source: [运行脚本](https://xxtouch.app/docs/URLScheme/Launch.md)
Path: URLScheme/Launch.md

# 运行脚本

```
xxt://launch/
```
```
xxt://launch/?path=%@
```

`path` 为要运行的脚本绝对路径。若不指定 `path` 参数，则运行当前选中的脚本。

- 二维码字典

```json
{
    "event":"launch",
    "path":"[要运行的脚本绝对路径]"
}
```

---

Source: [停止脚本](https://xxtouch.app/docs/URLScheme/Stop.md)
Path: URLScheme/Stop.md

# 停止脚本

```
xxt://stop/
```

停止当前运行的脚本。

- 二维码字典

```json
{
    "event":"stop"
}
```

---

Source: [绑定授权](https://xxtouch.app/docs/URLScheme/License.md)
Path: URLScheme/License.md

# 绑定授权

```
xxt://license/
```
```
xxt://license/?code=%@
```

唤醒授权界面并填写授权码。`code` 为 12 或 16 位授权码文本。

- 二维码字典

```json
{
    "event":"license",
    "code":"[授权码文本]"
}
```

---

Source: [XUI 相关](https://xxtouch.app/docs/URLScheme/XUI.md)
Path: URLScheme/XUI.md

# XUI 相关

```
xxt://xui/?bundle=%@&name=%@
```

配置指定脚本包，并唤醒其中的某个 XUI 文件。`bundle` 为脚本包的绝对路径，`name` 为 XUI 文件在脚本包中的相对路径。

- 二维码字典

```json
{
    "event":"xui",
    "bundle":"[脚本包的绝对路径]",
    "name":"[XUI 文件在脚本包中的相对路径]"
}
```

---

Source: [下载相关](https://xxtouch.app/docs/URLScheme/Download.md)
Path: URLScheme/Download.md

# 下载相关

```
xxt://download/?path=%@&url=%@
```

从指定 URL 下载文件。`path` 为保存的文件名，`url` 为目标下载地址。

- 说明
    - 若不指定 `path`，文件名将自动从目标 URL 推断，或取 URL 的最后一段作为文件名。
    - `path` 支持绝对路径或相对路径。若为相对路径，则相对于 App 文件浏览器当前所在目录。


- 二维码字典

```json
{
    "event":"download",
    "path":"[需要保存的文件名.lua]",
    "url":"[下载地址]"
}
```

---

Source: [恢复工作区](https://xxtouch.app/docs/URLScheme/Workspace.md)
Path: URLScheme/Workspace.md

# 恢复工作区

```
xxt://workspace/
```

将 XXTouch App 恢复到初始状态，退出所有已打开的界面。

- 二维码字典

```json
{
    "event":"workspace"
}
```

---

Source: [常见问题答疑目录](https://xxtouch.app/docs/FAQ/index.md)
Path: FAQ/README.md

# 常见问题答疑目录

---

- [XXTouch 是什么？](faq-0001.md)
- [哪些设备可运行 XXTouch？](faq-0002.md)
- [如何安装 XXTouch 到设备上？](faq-0003.md)
- [XXTouch 收费么？哪些部分收费？](faq-0004.md)
- [我购买了 XXTouch 授权码后会获得哪些权利？](faq-0005.md)
- [没有授权的 XXTouch 有什么限制？](faq-0006.md)
- [我电脑上有个脚本，如何使用 USB 连接导入到设备上？](faq-0007.md)
- [无根越狱相对于传统越狱有什么优劣？](faq-0008.md)
- [XXTouch 的脚本及相关资源存在设备的哪个位置？](faq-0009.md)
- [如何在电脑上给 XXTouch 开发脚本？](faq-0010.md)
- [作为开发者，我编写了一个脚本想收费怎么办？](faq-0011.md)
- [从 Cydia 添加 XXTouch 源出现“此服务器的证书无效。”怎么办？](faq-0012.md)
- [从 Cydia 安装或更新 XXTouch 失败（出现红字/黄字）怎么办？](faq-0013.md)
- [在 Cydia 添加 XXTouch 官方源失败怎么办？](faq-0014.md)
- [在 Cydia 的 XXTouch 官方源中找不到任何软件包怎么办？](faq-0015.md)
- [XXTouch 闪退或桌面没有图标或图标点不开怎么办？](faq-0016.md)
- [安装 XXTouch 后无限提示同步失败怎么解决？](faq-0017.md)
- [安装 XXTouch 后无限提示需要注销、与服务器或守护进程通讯失败？](faq-0018.md)
- [无根、隐根、巨魔版 XXTouch 有些什么限制？](faq-0019.md)
- [授权没有到期却弹出授权无效的提示？](faq-0020.md)
- [隐根 (roothide) 环境有何特殊？](faq-0021.md)
- [iOS 系统时间在哪里调整？](faq-0022.md)
- [取色器/编辑器/局域网控制器 扫描不到设备怎么办？](faq-0023.md)
- [为何我扫一扫下载会出现 “帧框加载已失败”？](faq-0024.md)
- [如何录制脚本？](faq-0025.md)
- [如何运行脚本？](faq-0026.md)
- [如何选择需要运行的脚本？](faq-0027.md)
- [如何在设备上编辑脚本？](faq-0028.md)
- [如何加密脚本？](faq-0029.md)
- [脚本可以做什么？](faq-0030.md)
- [加密的脚本可以被解密么？](faq-0031.md)
- [XXTouch 可以在电脑上运行么？](faq-0032.md)
- [XXTouch 可以在安卓系统上运行么？](faq-0033.md)
- [如何安装 TrollStore（巨魔）到设备上？](faq-0034.md)

---

Source: [XXTouch 是什么？](https://xxtouch.app/docs/FAQ/faq-0001.md)
Path: FAQ/faq-0001.md

# XXTouch 是什么？

XXTouch 是一款运行在越狱 iOS 环境下的自动化工具。
开发者可编写 Lua 脚本，由 XXTouch 执行以完成各类日常自动化任务。XXTouch 本身并不内置任何具体的业务脚本，也不会自动生成针对特定场景的脚本。

如需自行编写脚本，请参阅：
- [《XXTouch iOS 开发手册》](/docs/handbook/index.md)
- [《Lua 5.3 参考手册》](https://cloudwu.github.io/lua53doc/manual.html)

---

Source: [哪些设备可运行 XXTouch？](https://xxtouch.app/docs/FAQ/faq-0002.md)
Path: FAQ/faq-0002.md

# 哪些设备可运行 XXTouch？

---

## iOS 9.0 及以上、可越狱或可使用巨魔的所有 iOS 设备

XXTouch 不支持 XinA 越狱。如果您使用了该工具越狱，请改用 [Dopamine](https://ellekit.space/dopamine/) 或 [palera1n](https://palera.in/) 重新越狱。

以下支持范围核对于 2026 年 11 月 5 日，iOS 版本范围也适用于对应的 iPadOS 版本。实际可用版本还取决于设备能运行的系统版本，请同时核对各工具的设备兼容列表。

### 支持巨魔 (TrollStore) 安装

[TrollStore](https://ios.cfw.guide/installing-trollstore/) 支持 iOS 14.0 到 16.6.1、16.7 RC (20H18)、17.0.0

### 支持的无根 (rootless) 越狱

[Dopamine 3.x](https://ellekit.space/dopamine/) 的支持范围如下：

| 芯片 | iOS / iPadOS 版本 |
| --- | --- |
| A8 到 A11 (arm64) | 15.0 到 18.7.1 |
| A12 / A13 | 15.0 到 18.7.1、26.0 到 26.0.1 |
| A14 到 A16 / M1 到 M2 | 15.0 到 17.3.1 |
| A17 Pro | 17.0 到 17.3.1 |

[palera1n](https://palera.in/) 支持 iOS 15.0 及以上，仅限 A8 到 A11 设备。

### 支持的隐根 (roothide) 越狱

[Bootstrap](https://github.com/roothide/Bootstrap) 支持 iOS 15.0 到 16.6.1、16.7 RC (20H18)、17.0.0

[Dopamine-Roothide 3.x](https://github.com/roothide/Dopamine-roothide) 的芯片与系统版本支持范围与上表 Dopamine 3.x 相同。

[Relaxin](https://relaxin.owngoal.dev/) 是隐根 (roothide) 越狱，目前处于公开测试阶段。v0.5.7 的支持范围如下：

| 芯片 | iOS / iPadOS 版本 |
| --- | --- |
| A10 / A10X | 16.1 到 18.7.1 |
| A11 | 16.1 到 16.7.16 |
| A12 / A13 | 16.1 到 18.7.1、26.0 到 26.0.1 |
| A14 到 A16 / M1 到 M2 | 16.1 到 17.3.1 |
| A17 Pro | 17.0 到 17.3.1 |

其中 iOS / iPadOS 16.1 到 16.4.1 为实验性支持。

### 支持的传统 (rootful) 越狱

[palera1n](https://palera.in/) 支持 iOS 15.0 及以上，仅限 A8 到 A11 设备。
[checkra1n](https://checkra.in/) 支持 iOS 12.0 到 14.8.1，仅限 A7 到 A11 设备。
[Taurine](https://taurine.app/) 支持 iOS 14.0 到 14.8.1
[unc0ver](https://ios.cfw.guide/installing-unc0ver/) 支持 iOS 11.0 到 14.8
[Electra](https://ios.cfw.guide/installing-electra/) 支持 iOS 11.0 到 11.4.1
[doubleH3lix](https://ios.cfw.guide/installing-doubleh3lix-ipa/) 支持 iOS 10.0 到 10.3.3，仅限 A7 到 A9 设备。
[pangu933](https://ios.cfw.guide/installing-pangu933/) 支持 iOS 9.2 到 9.3.3
[pangu9](https://ios.cfw.guide/installing-pangu9/) 支持 iOS 9.0 到 9.0.2

---

Source: [如何安装 XXTouch 到设备上？](https://xxtouch.app/docs/FAQ/faq-0003.md)
Path: FAQ/faq-0003.md

# 如何安装 XXTouch 到设备上？

请先确认您的设备满足以下条件：
- 设备为 iOS 设备
- 设备已完成[越狱](https://dkxuanye.cn/?cat=116)，或已安装[巨魔 (TrollStore)](./faq-0034.md)

---

## 在越狱环境安装

越狱完成后，在 Cydia 或 Sileo 中添加软件源 [https://xxtouch.app/](https://xxtouch.app/)，然后安装 XXTouch。

---

## 使用巨魔 (TrollStore) 安装

安装前，请先从 Sileo 或 Cydia 卸载已有的越狱版 XXTouch。

### 在线安装方法

- 在设备上用 `Safari` 打开 [https://xxtouch.app/](https://xxtouch.app/)
- 长按 `巨魔版 TIPA` → 拷贝链接
- 打开 `TrollStore` → 点击`右上角 +` → `Install from URL` → 粘贴链接 → `Install`

### 离线安装方法

- 在电脑上打开 [https://xxtouch.app/](https://xxtouch.app/)，点击 `巨魔版 TIPA` 下载安装包
- **macOS**：使用隔空投送将 `.tipa` 文件发送到已安装 TrollStore 的设备，在设备上确认安装即可
- **Windows**：
    - 在设备上安装 `ES 文件浏览器`，然后通过爱思助手将 `.tipa` 文件传入 ES 文件浏览器的存档目录
    - 在设备上打开 `文件 (Files)` → `我的 iPhone/iPad`，找到 ES 文件浏览器的存档，分享到 `TrollStore` 打开

---

Source: [XXTouch 收费么？哪些部分收费？](https://xxtouch.app/docs/FAQ/faq-0004.md)
Path: FAQ/faq-0004.md

# XXTouch 收费么？哪些部分收费？

---

## XXTouch 是否收费？

是的，XXTouch 是付费软件。

## 哪些功能需要付费？

运行脚本的功能需要付费授权。

## 参考价格

```
月卡（ 31 天）授权码  40 元每设备
年卡（366 天）授权码 100 元每设备
```

## 购买说明

授权码是您在 XXTouch 上的唯一购买凭证，不记名、丢失不补，购买后请妥善保管。
授权码费用仅涵盖 XXTouch 应用本体的使用权，不包含脚本开发、教学培训等任何附加服务，也不附带论坛、QQ 群等社区中的社交特权。
**购买前，请务必了解购买后您将获得的[权利](faq-0005.md)以及将解除的[限制](faq-0006.md)。**


## 购买方式

自动发卡：[http://vip1.lat/L1PF](http://vip1.lat/L1PF)


## [如何使用授权码？](/docs/ABC/index.md#授权码如何激活)

---

Source: [我购买了 XXTouch 授权码后会获得哪些权利？](https://xxtouch.app/docs/FAQ/faq-0005.md)
Path: FAQ/faq-0005.md

# 我购买了 XXTouch 授权码后会获得哪些权利？

## 关于授权码与试用期

一个授权码可激活任意一台已安装且能正常运行 XXTouch 的设备。
每台设备均可获得一次性 168 小时的**全功能试用**授权——建议先充分试用，确认满足需求后再购买。

## 授权转移说明

- 零售月卡授权码可解绑 2 次
- 零售年卡授权码可解绑 8 次
- 授权绑定到设备后，24 小时内无法解绑
- 授权剩余时间不足 7 天时，无法从该设备转出授权

## 授权有效性说明

更换电池、卸载重装、更新软件、卸载越狱后重新越狱，均**不会影响**设备的授权状态。

---

Source: [没有授权的 XXTouch 有什么限制？](https://xxtouch.app/docs/FAQ/faq-0006.md)
Path: FAQ/faq-0006.md

# 没有授权的 XXTouch 有什么限制？

## 限制

- 未授权的 XXTouch 单次运行脚本的时长上限为 5 分钟。
- 未授权的设备无法加密脚本。

## 试用期说明

每台设备可获得一次性 168 小时的**全功能试用**授权。
首次在设备上尝试运行脚本时，试用授权自动激活。
试用期内无任何功能限制，试用期与付费授权在功能上完全一致。

## 无需授权即可使用的功能

以下功能**不需要授权**即可正常使用：
- 远程接口（如远程截图、远程文件访问等）
- 设备端代码编辑器
- 设备端及电脑端的取色工具

---

Source: [我电脑上有个脚本，如何使用 USB 连接导入到设备上？](https://xxtouch.app/docs/FAQ/faq-0007.md)
Path: FAQ/faq-0007.md

# 我电脑上有个脚本，如何使用 USB 连接导入到设备上？

使用 iTools 或其他支持连接 iOS 设备的手机助手，将脚本文件传输到设备上的以下目录：
```bash
<用户系统>/1ferver/lua/scripts/
```
**注**：`用户系统` 是 iTools 中文件管理的显示名称，不同助手的叫法可能不同，常见名称有 `用户系统`、`文件系统（用户）` 等。

---

Source: [无根越狱相对于传统越狱有什么优劣？](https://xxtouch.app/docs/FAQ/faq-0008.md)
Path: FAQ/faq-0008.md

# 无根越狱相对于传统越狱有什么优劣？

## 优势

- 系统文件为只读挂载，能有效防止误删系统文件
- 可直接使用"还原所有内容和设置"来抹除设备，无需额外处理

## 劣势

- 由于系统文件只读，与传统越狱的安装包不兼容

---

Source: [XXTouch 的脚本及相关资源存在设备的哪个位置？](https://xxtouch.app/docs/FAQ/faq-0009.md)
Path: FAQ/faq-0009.md

# XXTouch 的脚本及相关资源存在设备的哪个位置？

| 用途 | 路径 |
| --- | --- |
| 脚本目录 | `/var/mobile/Media/1ferver/lua/scripts/` |
| 插件目录 | `/var/mobile/Media/1ferver/lib/` |
| 资源目录 | `/var/mobile/Media/1ferver/res/` |
| 日志目录 | `/var/mobile/Media/1ferver/log/` |
| 文字识别字库目录 | `/var/mobile/Media/1ferver/tessdata/` |
| 文字识别推理模型目录 | `/var/mobile/Media/1ferver/models/` |
| 内置脚本模块目录 | `/var/mobile/Media/1ferver/lua/` |

无根越狱环境下，可能需要使用 [jbroot](/docs/handbook/develop-helper/jbroot.md) 来获取实际路径。

---

Source: [如何在电脑上给 XXTouch 开发脚本？](https://xxtouch.app/docs/FAQ/faq-0010.md)
Path: FAQ/faq-0010.md

# 如何在电脑上给 XXTouch 开发脚本？

- [下载开发工具](/docs/handbook/supplement/dev-tools.md)
- [阅读开发手册](/docs/handbook/index.md)

---

Source: [作为开发者，我编写了一个脚本想收费怎么办？](https://xxtouch.app/docs/FAQ/faq-0011.md)
Path: FAQ/faq-0011.md

# 作为开发者，我编写了一个脚本想收费怎么办？

XXTouch 目前暂无官方代售或验证平台业务。

## 可选方案

- 自行部署验证服务
- 在脚本中自行实现收费与授权验证逻辑
- 接入第三方验证平台提供的服务

---

Source: [从 Cydia 添加 XXTouch 源出现“此服务器的证书无效。”怎么办？](https://xxtouch.app/docs/FAQ/faq-0012.md)
Path: FAQ/faq-0012.md

# 从 Cydia 添加 XXTouch 源出现“此服务器的证书无效。”怎么办？

首先，确认官方源地址是否正确：
- [**xxtouch.app**](https://xxtouch.app)

然后依次排查以下事项：
- 停用设备上的网络代理及 VPN
- 确保设备的网络连接畅通
- 确认设备的时间和时区是否正确
  - 可[百度搜索"时间"](https://www.baidu.com/s?wd=时间)，然后[手动校准](faq-0022.md)

---

Source: [从 Cydia 安装或更新 XXTouch 失败（出现红字/黄字）怎么办？](https://xxtouch.app/docs/FAQ/faq-0013.md)
Path: FAQ/faq-0013.md

# 从 Cydia 安装或更新 XXTouch 失败（出现红字/黄字）怎么办？

## 解决因系统分区空间不足导致的红字

如果红字中包含以下任一信息：
**No space left on device**
**cannot copy extracted data for**
**failed in buffer_write(fd) (8, ret=-1)**
说明设备系统分区空间不足。
可尝试卸载不需要的插件或删除无用资源来释放空间。
**切勿删除** `/.cydia_no_stash` 文件来腾出空间，否则会导致白苹果！

## iOS 9\.2 ~ 10\.2\.1（不含 9\.3\.5）空间不足的可能解决方案

第一步，接通电源并保持持续供电。删除除 Cydia/Telesphoreo 及 XXTouch 以外的所有源（不会有任何损失，放心操作）。
- 操作方法：点击"软件源"右上角的"编辑"，然后点击源前面的红色减号图标

第二步，添加 **apt\.abcydia\.com**（雷锋源）
第三步，在 Cydia 中选择卸载 **Cydia Substrate**，并将卸载列表截图。**先不要点确认**，请仔细阅读以下提示：
- 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由您信任的专业人士处理。
- 理解上述声明后，自行决定是否确认卸载。

第四步，在 Cydia 中搜索并安装"**Stashing 容量不足修正**"插件
第五步，空间已充足。如有需要，将第三步中卸载的插件重新安装回来。

## 使用 Phœnix 越狱的 iOS 9\.3\.5 空间不足的可能解决方案

第一步，接通电源并保持持续供电。删除除 Cydia/Telesphoreo 及 XXTouch 以外的所有源（不会有任何损失）。
- 操作方法：点击"软件源"右上角的"编辑"，然后点击源前面的红色减号图标

第二步，添加 **cydia\.angelxwind\.net**（蔡明美源）和 **apt\.abcydia\.com**（雷锋源）
第三步，在 Cydia 中选择卸载 **Cydia Substrate**，并将卸载列表截图。**先不要点确认**，请仔细阅读以下提示：
- 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由专业人士处理。
- 理解上述声明后，自行决定是否确认卸载。

第四步，在 Cydia 中搜索并安装"**Stashing 容量不足修正**"和"**Stashing Fix for Phœnix (9\.3\.5)**"
第五步，按提示重启设备
第六步，重新激活越狱。空间已充足，如有需要，将第三步中卸载的插件重新安装回来。

## 删除可能导致红字/黄字的源

删除除 Cydia/Telesphoreo 及 XXTouch 以外的所有源（不会有任何损失）：
- BigBoss、ModMyi、ZodTTD、Ultrasn0w 也需要删除
- 操作方法：点击"软件源"右上角的"编辑"，然后点击源前面的红色减号图标
- 放心操作，不会有任何损失

## 搜索红字内容以寻找解决方案

常见的 Cydia 红字错误在网上通常有详尽的解答，建议先通过搜索引擎查找。

## 其他尝试

若以上方案均无效，请将红字界面截图，交由专业人士协助解决。
[专业 Cydia 红字修复](https://s.taobao.com/search?q=Cydia+%E7%BA%A2%E5%AD%97&)

---

Source: [在 Cydia 添加 XXTouch 官方源失败怎么办？](https://xxtouch.app/docs/FAQ/faq-0014.md)
Path: FAQ/faq-0014.md

# 在 Cydia 添加 XXTouch 官方源失败怎么办？

首先，确认官方源地址是否正确：
- [**xxtouch.app**](https://xxtouch.app)

将设备的时区调整为北京时间，并校正日期和时间：
- 可[百度搜索"时间"](https://www.baidu.com/s?wd=时间)，然后[手动校准](faq-0022.md)

确认无误后，可尝试以下操作：
- 确保网络连接正常
- 删除除 Cydia/Telesphoreo 及 XXTouch 以外的所有源（不会有任何损失）
    - 操作方法：点击"软件源"右上角的"编辑"，然后点击源前面的红色减号图标
- 点击"软件源"页面左上角的"刷新"并等待完成
- 如出现红字或黄字，请参阅[《从 Cydia 安装 XXTouch 失败（出现红字/黄字）怎么办？》](faq-0013.md)

---

Source: [在 Cydia 的 XXTouch 官方源中找不到任何软件包怎么办？](https://xxtouch.app/docs/FAQ/faq-0015.md)
Path: FAQ/faq-0015.md

# 在 Cydia 的 XXTouch 官方源中找不到任何软件包怎么办？

首先，确认官方源地址是否正确：
- [**xxtouch.app**](https://xxtouch.app)

然后尝试以下操作：
- 点击"软件源"页面左上角的"刷新"并等待完成
- 检查"已安装"列表中的 XXTouch 版本
    - 当设备上安装的版本号高于源上的版本时，源中不会显示该软件包
    - 这通常出现在安装了 XXTouch 测试版的情况下
    - 此为正常现象，无需进一步排查
- 如果不属于上述情况，请尝试：
    - 确保网络连接正常
    - 删除除 Cydia/Telesphoreo 及 XXTouch 以外的所有源（不会有任何损失）
        - 操作方法：点击"软件源"右上角的"编辑"，然后点击源前面的红色减号图标
    - 点击"软件源"页面左上角的"刷新"并等待完成
    - 如出现红字或黄字，请参阅[《从 Cydia 安装 XXTouch 失败（出现红字/黄字）怎么办？》](faq-0013.md)

---

Source: [XXTouch 闪退或桌面没有图标或图标点不开怎么办？](https://xxtouch.app/docs/FAQ/faq-0016.md)
Path: FAQ/faq-0016.md

# XXTouch 闪退或桌面没有图标或图标点不开怎么办？

请**逐条**尝试以下方案：

---

## 主屏幕上的 XXT 图标消失了

- 若使用多巴胺 (Dopamine) 越狱且启用了"隐藏越狱"，取消该选项即可恢复
- 否则尝试打开 `TrollStore` → `Rebuild Icon Cache`
- 若仍未出现，请从 Cydia 或 Sileo 重新安装 XXTouch

## 巨魔版 XXT 和 TrollStore 都打不开了

打开巨魔持久助手 (`Persistence Helper`)——例如，如果之前已注入到"提示 (Tips)"中，则打开"提示"应用。
点击 `Refresh App Registrations`，等待完成即可修复。

## 卸载重装 XXTouch

从 Cydia 或 Sileo 直接重新安装最新版 XXTouch（无需先卸载），确保**没有**出现错误。
然后重启设备（可能还需要重新激活越狱）。

## 排查插件冲突

从 Cydia 或 Sileo 卸载可能产生冲突的插件，重新安装 XXTouch 后重启设备（可能还需要重新激活越狱）。

---

Source: [安装 XXTouch 后无限提示同步失败怎么解决？](https://xxtouch.app/docs/FAQ/faq-0017.md)
Path: FAQ/faq-0017.md

# 安装 XXTouch 后无限提示同步失败怎么解决？

请根据您的安装方式，**逐条**尝试对应方案。

---

## 通过 Sileo 安装的 XXTouch

### 尝试 1

点击取消，然后选择一个脚本。

### 尝试 2

从 Sileo 直接重新安装最新版 XXTouch（无需先卸载），确保**没有**出现错误。
重启设备（可能还需重新激活越狱）。

### 尝试 3

1. 通过 Sileo 安装 **OpenSSH**，确保安装无错误（已安装则跳过）
2. 在 Sileo 中选择卸载 **Substitute** 或 **ElleKit**，将卸载列表截图。**先不要确认**，请阅读以下提示：
   - 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由专业人士处理。
   - 理解上述声明后，自行决定是否确认。
3. 通过源安装 XXTouch（可能需重启设备并重新激活越狱），确保**没有**出现错误
4. 再次重启设备（可能需重新激活越狱）
5. 如有需要，参照截图将卸载的插件重新安装回来

### 尝试 4

删除 `/var/mobile/Media/1ferver/caches/daemon_cache.db`，然后重启设备（可能需重新激活越狱）。


## 通过 Cydia 安装的 XXTouch

### 尝试 1

点击取消，然后选择一个脚本。

### 尝试 2

从 Cydia 直接重新安装最新版 XXTouch（无需先卸载），确保**没有**出现红字（参阅[《从 Cydia 安装 XXTouch 失败（出现红字/黄字）怎么办？》](faq-0013.md)）。
重启设备（可能需重新激活越狱）。

### 尝试 3

1. 通过 Cydia 安装 **OpenSSH**，确保无红字（已安装则跳过）
2. 刷新 Cydia 源并更新所有基础依赖，确保无红字
3. 重新安装（无需先卸载）核心组件和 XXTouch，确保无红字：
   - iOS 11 以下：**Cydia Substrate**、**UIKit Tools** 和 XXTouch
   - iOS 11 及以上：**Tweak Injector**、**Substitute**、**Substrate Compatibility Layer**、**UIKit Tools** 和 XXTouch
4. 重启设备（可能需重新激活越狱）

### 尝试 4

1. 在 Cydia 中选择卸载 **Cydia Substrate**（iOS 11 及以上为 **Substitute**），将卸载列表截图。**先不要确认**，请阅读以下提示：
   - 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由专业人士处理。
   - 理解上述声明后，自行决定是否确认。
2. 通过源安装 XXTouch（可能需重启设备并重新激活越狱），确保无红字
3. 再次重启设备（可能需重新激活越狱）
4. 如有需要，参照截图将卸载的插件重新安装回来

### 尝试 5

删除 `/var/mobile/Media/1ferver/caches/daemon_cache.db`，然后重启设备（可能需重新激活越狱）。

---

Source: [安装 XXTouch 后无限提示需要注销、与服务器或守护进程通讯失败？](https://xxtouch.app/docs/FAQ/faq-0018.md)
Path: FAQ/faq-0018.md

# 安装 XXTouch 后无限提示需要注销、与服务器或守护进程通讯失败？

请根据您的安装方式，**逐条**尝试对应方案。

---

## 通过 Sileo 安装的 XXTouch

### 尝试 1

点击取消，然后选择一个脚本。

### 尝试 2

从 Sileo 直接重新安装最新版 XXTouch（无需先卸载），确保**没有**出现错误。
重启设备（可能还需重新激活越狱）。

### 尝试 3

1. 通过 Sileo 安装 **OpenSSH**，确保安装无错误（已安装则跳过）
2. 在 Sileo 中选择卸载 **Substitute** 或 **ElleKit**，并将卸载列表截图。**先不要确认**，请仔细阅读以下提示：
   - 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由专业人士处理。
   - 理解上述声明后，自行决定是否确认。
3. 通过源安装 XXTouch（可能需重启设备并重新激活越狱），确保**没有**出现错误
4. 再次重启设备（可能需重新激活越狱）
5. 如有需要，参照截图将卸载的插件重新安装回来

### 尝试 4

删除 `/var/mobile/Media/1ferver/caches/daemon_cache.db`，然后重启设备（可能需重新激活越狱）。


## 通过 Cydia 安装的 XXTouch

### 尝试 1

点击取消，然后选择一个脚本。

### 尝试 2

从 Cydia 直接重新安装最新版 XXTouch（无需先卸载），确保**没有**出现红字（参阅[《从 Cydia 安装 XXTouch 失败（出现红字/黄字）怎么办？》](faq-0013.md)）。
重启设备（可能还需重新激活越狱）。

### 尝试 3

1. 通过 Cydia 安装 **OpenSSH**，确保无红字（已安装则跳过）
2. 刷新 Cydia 源并更新所有基础依赖，确保无红字
3. 重新安装（无需先卸载）核心组件和 XXTouch，确保无红字：
   - iOS 11 以下：**Cydia Substrate**、**UIKit Tools** 和 XXTouch
   - iOS 11 及以上：**Tweak Injector**、**Substitute**、**Substrate Compatibility Layer**、**UIKit Tools** 和 XXTouch
4. 重启设备（可能需重新激活越狱）

### 尝试 4

1. 在 Cydia 中选择卸载 **Cydia Substrate**（iOS 11 及以上为 **Substitute**），将卸载列表截图。**先不要确认**，请仔细阅读以下提示：
   - 此操作会同时卸载包括 XXTouch 在内的许多插件。理论上不存在风险，但我们不承担由此产生的任何责任。如有顾虑，请终止操作并交由专业人士处理。
   - 理解上述声明后，自行决定是否确认。
2. 通过源安装 XXTouch（可能需重启设备并重新激活越狱），确保无红字
3. 再次重启设备（可能需重新激活越狱）
4. 如有需要，参照截图将卸载的插件重新安装回来

### 尝试 5

删除 `/var/mobile/Media/1ferver/caches/daemon_cache.db`，然后重启设备（可能需重新激活越狱）。

---

Source: [无根、隐根、巨魔版 XXTouch 有些什么限制？](https://xxtouch.app/docs/FAQ/faq-0019.md)
Path: FAQ/faq-0019.md

# 无根、隐根、巨魔版 XXTouch 有些什么限制？

iOS 15 及以上系统的系统分区均为只读。

---

## 巨魔版 XXTouch 的限制

- `alerthelper` 模块无法正常工作
- `dialog` 和 `webview` 的流畅度不及完整越狱版
- 无法使用 `os.execute` 和 `io.popen` 函数

## 巨魔版 XXTouch 的优势

- 不依赖越狱环境即可运行
- 可通过添加主屏幕小组件实现开机自启动

## Bootstrap 越狱环境的限制

- XXTouch 后台服务不会随 Bootstrap 自动启动
- `alerthelper` 模块无法正常工作
- `dialog` 和 `webview` 的流畅度不及完整越狱版
- `webview` 浮窗中无法弹出软键盘输入文字
- 详情参阅 [XXTouch 于 Bootstrap 环境说明](faq-0021.md#xxtouch-于-bootstrap-环境说明)

## Dopamine-Roothide 的限制

- 几乎没有限制
- 详情参阅[隐根 (roothide) 环境有何特殊？](faq-0021.md)

## 无根越狱的限制

- 几乎没有限制

---

Source: [授权没有到期却弹出授权无效的提示？](https://xxtouch.app/docs/FAQ/faq-0020.md)
Path: FAQ/faq-0020.md

# 授权没有到期却弹出授权无效的提示？

请依次排查以下事项：

1. 将设备的时区调整为北京时间，并确保日期和时间正确
   - 时间容差为 5 分钟，可[百度搜索"时间"](https://www.baidu.com/s?wd=时间)后[手动校准](faq-0022.md)

2. 确保设备网络连接畅通
   - 设备上的网络代理或 VPN 可能导致连接异常

如以上排查均无效，请截图并联系经销商处理。

---

Source: [隐根 (roothide) 环境有何特殊？](https://xxtouch.app/docs/FAQ/faq-0021.md)
Path: FAQ/faq-0021.md

# 隐根 (roothide) 环境有何特殊？

隐根 (roothide) 是有别于有根 (rootful) 和无根 (rootless) 的第三种越狱环境。

---

## 与有根 (rootful) 及无根 (rootless) 的区别

与传统越狱不同，roothide 环境中`越狱根 (jbroot)` 与`系统根 (rootfs)` 是相互隔离的。
`越狱根` 挂载于 `系统根` 中的一个随机路径，同时 `系统根` 也反向挂载于 `越狱根/rootfs/` 路径上。


## 系统根 rootfs

在 roothide 环境中，`系统根` 即 iOS 系统的原始根目录，未经任何修改，不包含额外路径。


## 越狱根 jbroot

`越狱根` 挂载于 `系统根` 下的一个随机路径，
通常位于 `/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/`（长串 X 为随机值）。
通过 `jbroot` 函数，可以将普通路径转换为越狱根中的对应路径。
例如，要访问越狱根中的 `/var/mobile/Media/1.txt`，应使用 `jbroot("/var/mobile/Media/1.txt")`。
在脚本中执行 `f = io.open(jbroot("/var/mobile/Media/1.txt"), "r")` 时，实际打开的文件为：
```bash
/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/var/mobile/Media/1.txt
```


## Shell 环境

如前所述，越狱根挂载于系统根中的一个随机路径。
然而在 Shell 环境中（例如 deb 安装脚本），无法预知越狱根在系统根中的具体位置。
因此，roothide 将 Shell 脚本的运行时根设定为`越狱根`。
也就是说，deb 中的 `/Applications/XXTExplorer.app` 实际会被安装到：
```bash
/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/Applications/XXTExplorer.app
```

这确保了 deb 安装的越狱插件不会污染`系统根`。
但这也引入了一个问题：在 XXTouch 中使用 `os.execute` 或 `io.popen` 时，
由于这些函数通过 bash/zsh 执行 Shell 脚本，
调用 `os.execute("/usr/bin/hidutil list")` 实际执行的命令是：
```bash
/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/usr/bin/hidutil list
```

这导致无法直接从 Shell 中访问系统根路径。
为此，roothide 将`系统根`反向挂载到了`越狱根/rootfs/`。
于是，在脚本中执行 `os.execute("/rootfs/usr/bin/hidutil list")` 时，实际运行的命令就是：
```bash
/usr/bin/hidutil list
```


## 文件及目录镜像

`越狱根`中的部分文件和目录路径已设置为指向原始`系统根`的符号链接：

|越狱根中的路径|
|-|
|/dev|
|/private/preboot|
|/var/containers|
|/var/mobile/Containers|
|/usr/share/misc/trace.codes|
|/usr/share/zoneinfo|
|/etc/hosts.equiv|
|/etc/hosts|
|/var/run/utmpx|
|/var/db/timezone|
|/System/Library/CoreServices/SystemVersion.plist|

此外，XXTouch 的脚本路径 `/var/mobile/Media/1ferver` 也会在`系统根`中创建对应的符号链接。
上述路径在`越狱根`和`系统根`中均可直接访问。
[参考来源](https://github.com/roothide/Developer/blob/main/filemirror.md)


## XXTouch 于 Bootstrap 环境说明

### 无自动启动

使用 Bootstrap-Roothide 半越狱的设备在重启并重新激活 Bootstrap 后，XXTouch 后台服务不会自动启动。
需要手动打开 XXTouch App，应用会自动退出并显示 `Starting XXTouch Daemon...`，约 20 秒后后台服务即可就绪。

### 无桌面服务

若使用 Bootstrap 但未通过 Serotonin 激活桌面注入服务，XXTouch 脚本中与界面相关的功能将不可用：
- `dialog`、`webview` 等在顶层窗口创建界面的功能会受到影响
- `alerthelper` 处理桌面弹窗的功能无法工作

### 使用 XXTouch 清理 Bootstrap-Roothide 环境中可能被 App 检测到的文件

```Lua
local noexecute = require('no_os_execute')

function remove_sys_app_caches(name)
    noexecute.rm_rf('/var/root/Library/WebKit/'..name)
    noexecute.rm_rf('/var/root/Library/Caches/'..name)
    noexecute.rm_rf('/var/root/Library/HTTPStorages/'..name)
    noexecute.rm_rf('/var/root/Library/SplashBoard/Snapshots/'..name)
    noexecute.rm_rf('/var/root/Library/Saved Application State/'..name..'.savedState')
    noexecute.rm_rf('/var/root/Library/Preferences/'..name..'.plist')

    noexecute.rm_rf('/var/root/Library/WebKit/'..name)
    noexecute.rm_rf('/var/mobile/Library/Caches/'..name)
    noexecute.rm_rf('/var/mobile/Library/HTTPStorages/'..name)
    noexecute.rm_rf('/var/mobile/Library/SplashBoard/Snapshots/'..name)
    noexecute.rm_rf('/var/mobile/Library/Saved Application State/'..name..'.savedState')
    noexecute.rm_rf('/var/mobile/Library/Preferences/'..name..'.plist')
end

remove_sys_app_caches('com.opa334.Dopamine')
remove_sys_app_caches('org.coolstar.SileoStore')
remove_sys_app_caches('ws.hbang.Terminal')
remove_sys_app_caches('pisshill.usprebooter')
remove_sys_app_caches('com.samiiau.loader')
remove_sys_app_caches('kr.xsf1re.vnodebypass')
remove_sys_app_caches('com.serena.Antoine')
remove_sys_app_caches('wiki.qaq.TrollFools')
remove_sys_app_caches('com.tigisoftware.Filza')
remove_sys_app_caches('com.tigisoftware.Filza000')
remove_sys_app_caches('com.tigisoftware.ADManager')
remove_sys_app_caches('com.ichitaso.otadisablerts')
remove_sys_app_caches('chaoge.ChargeLimiter')
remove_sys_app_caches('com.xxtouch.XXTExplorer')

noexecute.rm_rf('/private/var/mobile/Library/Filza')
noexecute.rm_rf('/private/var/mobile/.ssh')
noexecute.rm_rf('/private/var/root/.ssh')
noexecute.rm_rf('/private/var/mobile/offsets.txt')
noexecute.rm_rf('/private/var/mobile/offsets.txt')
noexecute.rm_rf('/private/var/mobile/Serotonin.jp2')
noexecute.rm_rf('/private/var/mobile/Documents/kfund_offsets.plist')
noexecute.rm_rf('/private/var/iomfb_bics_daemon')
```

为什么会存在这些文件？
虽然 Roothide 将越狱应用安装到了随机路径中，但并未限制这些应用的运行时行为。
因此，越狱应用运行后产生的缓存或其他文件，仍然会写入到系统根的对应位置。

此外，App 还可能检测 SSH 端口。如有必要，可在 Bootstrap 设置界面中关闭 SSH 服务以避免被检测。

---

Source: [iOS 系统时间在哪里调整？](https://xxtouch.app/docs/FAQ/faq-0022.md)
Path: FAQ/faq-0022.md

# iOS 系统时间在哪里调整？

1. 打开**设置**应用。
2. 进入**通用**。
3. 进入**日期与时间**。

---

Source: [取色器/编辑器/局域网控制器扫描不到设备怎么办？](https://xxtouch.app/docs/FAQ/faq-0023.md)
Path: FAQ/faq-0023.md

# 取色器/编辑器/局域网控制器扫描不到设备怎么办？

请依次排查以下事项：
- 确保电脑端或路由器的防火墙规则未拦截相关连接
- 设备与电脑处于同一局域网
- 已停用设备上的网络代理及 VPN
- 设备处于解锁屏幕状态
- 电脑能 ping 通设备（如不熟悉，可[百度搜索"ping 命令如何使用"](https://www.baidu.com/s?wd=ping命令如何使用)）

确保设备已开启[远程开关](/docs/ABC/index.md#如何打开远程接口)。

---

Source: [为何扫一扫下载会出现"帧框加载已失败"？](https://xxtouch.app/docs/FAQ/faq-0024.md)
Path: FAQ/faq-0024.md

# 为何扫一扫下载会出现"帧框加载已失败"？

- 如果您是脚本分发者（脚本作者），请参阅 [XXTouch 扫一扫协议](/docs/URLScheme/Download.md)
- 如果您是脚本用户，请联系您的脚本分发者（脚本作者）参阅上述文档

---

Source: [如何录制脚本？](https://xxtouch.app/docs/FAQ/faq-0025.md)
Path: FAQ/faq-0025.md

# 如何录制脚本？

默认情况下，`按一下音量键`即可弹出菜单选择录制脚本。
再次`按一下音量键`可完成录制。
快捷键可在 `更多 → 按键设置` 中自定义。
图文说明：[如何录制脚本？](/docs/ABC/index.md#如何录制脚本)

---

Source: [如何运行脚本？](https://xxtouch.app/docs/FAQ/faq-0026.md)
Path: FAQ/faq-0026.md

# 如何运行脚本？

打开 XXTouch App 后，在"我的脚本"界面点击需要运行的脚本文件名。
默认情况下，`按一下音量键`即可弹出菜单选择启动选中脚本。
再次`按一下音量键`可选择暂停或停止脚本。
快捷键可在 `更多 → 按键设置` 中自定义。
图文说明：[如何运行已经选中的脚本？](/docs/ABC/index.md#如何运行已经选中的脚本)

---

Source: [如何选择需要运行的脚本？](https://xxtouch.app/docs/FAQ/faq-0027.md)
Path: FAQ/faq-0027.md

# 如何选择需要运行的脚本？

打开 XXTouch App 后，在"我的脚本"界面点击需要运行的脚本文件名即可选中。

---

Source: [如何在设备上编辑脚本？](https://xxtouch.app/docs/FAQ/faq-0028.md)
Path: FAQ/faq-0028.md

# 如何在设备上编辑脚本？

打开 XXTouch App 后，在"我的脚本"界面：
1. 点击脚本文件右侧的 `ⓘ` 按钮
2. 点击左侧出现的 `</>` 按钮即可进入编辑器

---

Source: [如何加密脚本？](https://xxtouch.app/docs/FAQ/faq-0029.md)
Path: FAQ/faq-0029.md

# 如何加密脚本？

- 图：[如何加密脚本](/docs/ABC/index.md#如何加密脚本)

---

Source: [脚本可以做什么？](https://xxtouch.app/docs/FAQ/faq-0030.md)
Path: FAQ/faq-0030.md

# 脚本可以做什么？

[《XXTouch iOS 开发手册》](/docs/handbook/index.md)

---

Source: [加密的脚本可以被解密么？](https://xxtouch.app/docs/FAQ/faq-0031.md)
Path: FAQ/faq-0031.md

# 加密的脚本可以被解密么？

不可以。
从源码到加密脚本的过程**是单向且不可逆的**。
源码可以加密为加密脚本，但加密脚本**无法还原为源码**。

---

Source: [XXTouch 可以在电脑上运行么？](https://xxtouch.app/docs/FAQ/faq-0032.md)
Path: FAQ/faq-0032.md

# XXTouch 可以在电脑上运行么？

不可以。
XXTouch 仅提供 iOS 版本。

---

Source: [XXTouch 可以在安卓系统上运行么？](https://xxtouch.app/docs/FAQ/faq-0033.md)
Path: FAQ/faq-0033.md

# XXTouch 可以在安卓系统上运行么？

不可以。
XXTouch 仅提供 iOS 版本。

---

Source: [如何安装 TrollStore（巨魔）到设备上？](https://xxtouch.app/docs/FAQ/faq-0034.md)
Path: FAQ/faq-0034.md

# 如何安装 TrollStore（巨魔）到设备上？

如果操作过程中遇到任何问题，可尝试切换到未遭受非法流量过滤的网络环境后再次尝试。

---

## 支持范围

- iOS 14.0 – 16.6.1
- iOS 16.7 RC (20H18)
- iOS 17.0.0

iOS 16.7.x、iOS 17.0.1 及以上版本 **不可安装 TrollStore**。

---

## iOS 15.1 及以下版本

请参考 [https://ios.cfw.guide/installing-trollstore/](https://ios.cfw.guide/installing-trollstore/) 中介绍的方法安装。

---

## iOS 15.2 – 16.6.1、16.7 RC (20H18)、17.0.0

可使用 [TrollRestore](https://github.com/JJTech0130/TrollRestore/releases) 将 `TrollStore`（巨魔安装助手）安装到设备。

### 准备工作

- 下载对应平台的 [TrollRestore](https://github.com/JJTech0130/TrollRestore/releases) 到电脑
- **Windows** 用户需要先安装 iTunes，或通过爱思助手安装苹果设备驱动
- 确保设备已关闭 `查找我的 iPhone`（路径：`设置 → [iCloud 账号名] → 查找`）
- 确保设备上已从 App Store 安装苹果官方 `提示 (Tips.app)` 应用

### 安装步骤

1. 使用命令行启动电脑端 `TrollRestore`
2. 当提示输入应用名称时，输入 `Tips` 然后按回车
    - 若提示 `Failed to find the removable system app 'Tips.app'`，请先到 App Store 搜索 `提示` 或 `Tips` 安装苹果官方的 `提示 (Tips.app)` 应用
    - 若提示 `Find My must be disabled in order to use this tool`，请在设备端 `设置 → [iCloud 账号名] → 查找` 中关闭 `查找我的 iPhone`
3. 等待设备自动重启
4. 重启完成后，在设备上打开 `提示 (Tips)`
5. 点击 `Install TrollStore`，等待设备注销
6. 回到主屏幕，打开 `TrollStore`
7. 进入 `TrollStore → Settings → Install Persistence Helper`，选择 `Tips` 安装巨魔持久助手（**这一步很重要**）

---

## TrollStore 图标变黑 / TrollStore 安装的 App 闪退

打开 `提示 (Tips)` → 点击 `Refresh App Registrations` 即可。

---

Source: [使用入门](https://xxtouch.app/docs/ABC/index.md)
Path: ABC/README.md

# 使用入门

---


## 授权码如何激活？

购买授权码后，按下图操作即可完成激活：
![授权码如何激活.gif-433.5kB](授权码如何激活.gif)

---

## 主界面说明图示

![主界面说明图示.png-101kB](主界面说明图示.png)

---

## 如何运行已经选中的脚本？

默认情况下，在任意界面`按一下音量键`即可弹出选择菜单：
![默认长按音量键会出现.jpg-24.4kB](默认长按音量键会出现.jpg)
选择`启动脚本`即可运行当前选中的脚本。
**注**：快捷键可在 `更多 → 按键设置` 中自定义。

---

## 如何录制脚本？

默认情况下，在任意界面`按一下音量键`即可弹出选择菜单：
![默认长按音量键会出现.jpg-24.4kB](默认长按音量键会出现.jpg)

选择`录制`即可开始录制。
再次`按一下音量键`可完成录制：
![录制完成提示.jpg-32kB](录制完成提示.jpg)

**注**：快捷键可在 `更多 → 按键设置` 中自定义。

---

## 如何加密脚本？

请确保满足以下条件：
- 设备上已安装最新版 XXTouch
- 设备与电脑处于同一局域网
- 设备与电脑之间网络互通

然后在设备上开启远程接口（参阅[《如何打开远程接口？》](#如何打开远程接口)），操作如下图所示：
![如何本地加密脚本.png-49.3kB](如何本地加密脚本.png)

---

## 如何打开远程接口？

打开 XXTouch 应用，进入 `更多 → 远程服务`，打开开关即可：
![激活远程开关.gif-86.4kB](激活远程开关.gif)
